Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
emacs from scratch
There are two ways of installing merlin: through opam and manually. If you do not wish to try the development version, it is recommended to install merlin through opam.
Keep your existing
Merlin doesn't provide syntax highlighting nor indentation.
It is a minor mode that can be enabled on top of one of the existing OCaml modes. It will add completion, navigation, etc on top.
Installing merlin and its emacs mode with opam
To install merlin with opam just issue
opam install merlin
It should download and install the last release of merlin. To check
that merlin is indeed installed (and that you have a well configured
opam) you can try to run
Then add the following at the end of your emacs configuration file (for instance
(let ((opam-share (ignore-errors (car (process-lines "opam" "config" "var" "share"))))) (when (and opam-share (file-directory-p opam-share)) (add-to-list 'load-path (expand-file-name "emacs/site-lisp" opam-share)) (autoload 'merlin-mode "merlin" nil t nil) (add-hook 'tuareg-mode-hook 'merlin-mode t) (add-hook 'caml-mode-hook 'merlin-mode t)))
Then whenever you start emacs, merlin will be loaded. Try it by issuing (in
M-x merlin-version. It should display the version of merlin you are using.
You can now skip the next section and play with merlin.
Installing merlin manually
To compile and install merlin, the process is standard:
git clone https://github.com/the-lambda-church/merlin.git cd merlin ./configure --prefix /usr/local make sudo make install
You can specify any path for the prefix, and merlin will install itself in this
directory (the default being
You can now run
ocamlmerlin to check if the installation is successful.
The process is similar to the installation with opam, you have to append to your
emacs configuration file (for instance
(add-to-list 'load-path "<PREFIX>/share/emacs/site-lisp") (autoload 'merlin-mode "merlin" nil t nil) (add-hook 'tuareg-mode-hook 'merlin-mode t) (add-hook 'caml-mode-hook 'merlin-mode t) (setq merlin-command "<PREFIX>/bin/ocamlmerlin")
<PREFIX> is the prefix you specified to the configure script of merlin
in the previous step. You can now restart emacs and check if that worked by
Discovering the emacs mode
To enable the mode, type:
If you wish to enable merlin whenever you open a ML buffer you can put the following in your configuration file:
(add-hook 'tuareg-mode-hook 'merlin-mode)
if you are using tuareg, or
(add-hook 'caml-mode-hook 'merlin-mode)
if you are using the caml-mode.
Synchronization and error reporting
Merlin works by running its own typechecker on your buffer. Synchronization is done automatically when you save your buffer, and when you call a command.
When calling a command, emacs and merlin reconcile their view of the buffer so that merlin always have fresh information to answer your query.
Upon saving emacs will ask merlin about all the errors (of syntax or type) in
your buffer and report them.
If your buffer contains error the erroneous chunks of the buffer will indeed be
highlighted and emacs will display markers in the margin (
! for errors,
You can jump to errors using the
merlin-error-next command (
C-c C-x by
Note the you can tell merlin not to report warnings using:
(setq merlin-report-warnings nil)
The emacs mode provides three ways to complete expressions:
completion-at-point: the native completion engine of emacs
auto-complete: a fancier completion system, installed by default on emacs 24, and available on marmalade.
company-mode: available on melpa, an alternative completion system (with a saner default configuration).
completion-at-point should work out of the box. To try it,
List.m followed by
M-x completion-at-point (bound to
default in emacs 24), it will display a completion buffer with the different
candidates and their types.
completion-at-point at work:
By default, if auto-complete is installed, merlin will only register a source
merlin-ac-source and do nothing about it. If you issue:
(setq merlin-ac-setup 'easy)
it will enable auto-complete in merlin buffers and add the merlin source to the
default sources. You can now use auto-complete as you usually do, or run
If you have not configured auto-complete, see its documentation.
Using auto-complete-mode you should see something looking like this:
If you want autocomplete to suggest completions without prompting, simply replace
t in the above
To use the company mode plugins, you just have to issue:
; Make company aware of merlin (with-eval-after-load 'company (add-to-list 'company-backends 'merlin-company-backend)) ; Enable company on merlin managed buffers (add-hook 'merlin-mode-hook 'company-mode) ; Or enable it globally: ; (add-hook 'after-init-hook 'global-company-mode)
And then it should work out of the box. See the documentation of company mode for more information.
Getting the types of expressions
To get the type of ident under the cursor, call
C-c C-t by default). It will highlight the ident and display its type.
You can then call
C-<down>) to climb the typed tree and see type
of bigger expressions surrounding the cursor.
The result should look something like this :
If there is an active region, it will instead display the type of the region.
Further calls to
C-c C-t will improve the verbosity of the displayed
type, by expanding aliases.
Also, note that
C-c t by default) will prompt you for an
arbitrary expression and will try to type it in the context active at your
You can navigate between phrases of your buffer using
C-c C-n) and
Merlin also provide a way to switch between files of your project using the
merlin-switch-to-mli, these will prompt you
for a (toplevel) module name, and will then open the associated ml[i] file.
And last but not least : the command
merlin-locate (bound to
C-c C-l by
default) when called on an identifier will try to bring you to the place were
it is introduced (i.e. defined or bound).
You can also use that facility from auto-complete completion menu; issuing
C-c C-l when that menu is open will call the locate command on the
Note that it might happen that merlin fails to find the definition location of the identifier you gave him. Several things might explain that:
- you are asking for the definition of something defined in an other file and:
- either that file is not in the load path of merlin (you need to setup a .merlin!)
- or you didn't compile with -bin-annot.
- you are asking him for the definition of something local to your file but the place where that thing is defined doesn't parse or doesn't typecheck, and the identifier is not present in the environment
If it doesn't work, but none of the above explains why, open an issue!
See project configuration for a full
You can use the
merlin-use command to tell Merlin that you're using
a findlib/opam package. This will prompt you for a package name
(completion on packages name is provided, but you can always call
ocamlfind list from a shell to have the list of installed packages).
This is equivalent to the
PKG directive in
You can enable syntax extensions with
M-x merlin-extension-enable. This is equivalent to
It happens that merlin and emacs get desynchronized. In this case,
you can always issue
merlin-restart-process to start from a fresh state.