These instructions are aimed at readers of Real World OCaml, though much of what you find here will be useful for anyone who wants to get a good working OCaml installation.
At the highest level, here's what you need to do:
- Install opam, OCaml's default package manager
- Set up opam, which means initializing opam and then installing the version of OCaml you'll need, along with the libraries and tools that will help you work through the examples in the book
- Configure utop, the interactive toplevel that will be the primary vehicle we'll use for walking through small examples.
- Set up your editing environment. We have pointers for a few editors, including Visual Studio Code, Emacs, and Vi
Note that Windows is not fully supported by the examples in Real World OCaml or by opam, though it's being worked on. Until that's ready, we recommend using a virtual machine running Debian Linux on your local machine, or Docker for Windows.
Let's get started.
opam is the default package manager for OCaml, and you'll need it to get everything else you need installed and set up.
The easiest way to install opam is through your OS's package manager. In most cases, installing opam will also trigger the installation of OCaml. The version installed isn't important, since we can use opam itself to install other versions of the compiler.
Here are platform-specific installation instructions for installing via your package manager. The same page has instructions for using a binary installer if you have trouble with your package manager.
Setting up opam
The entire opam package database is held in the
.opam directory in your home directory, including
compiler installations. On Linux and macOS, this will be the
~/.opam directory, which means you don't need
administrative privileges to configure it. If you run into
problems configuring opam, just delete the whole
~/.opam directory and start over.
Let's begin by initialising the opam package database. We do this by running:
opam init finishes, it will ask you if you
want it to adjust some of the config files for your shell. We
recommend you say yes here so as to automate adjusting the PATH
environment variable of your shell and to prepare your environment
in other ways.
Note that if for whatever reason your shell is not set up properly, you can put it in the right state by running:
eval $(opam env)
This evaluates the results of running
env in your current shell and sets the variables so that
subsequent commands will use them. This only works with
your current shell and it can only be automated for future shells by
adding the line to your login scripts (which is exactly what opam
offers to do for you in
You can check if your environment is set up properly by
opam switch with no arguments. It will emit
a warning if your shell is not set up correctly, along with
instructions on how to fix it.
opam switch # switch compiler description → default ocaml-base-compiler.4.09.1 default [WARNING] The environment is not in sync with the current switch. You should run: eval $(opam env)
Installing the right compiler
Real World OCaml requires OCaml 4.12.0. You can use
switch to see which version of OCaml you have installed.
If, as shown in the above invocation of switch, you have an
older version installed, you can use opam to install a more
opam switch create 4.12.0 eval $(opam env)
opam switch create will take a few minutes on a
modern machine, and will download and install the new compiler and
all libraries associated with it in
Installing libraries and tools
Finally, we're ready to install the libraries and tools we'll
need for the book. The two important ones are
which provides the standard library that all the examples in the
book are based on, and
utop, which is the
interactive toplevel that you can use for working through the
examples. We can install them as follows.
opam install base utop
But you'll probably want more than this as you work through the book. Here's a more complete list of libraries you should install:
opam install core async yojson core_extended \ core_bench cohttp-async async_graphics \ cryptokit menhir
If some of the above don't work, don't worry too much. Most of them come up in only a few places in the book.
Setting up and using
When you first run
utop, you'll find yourself at an
interactive prompt with a bar at the bottom of the screen. The
bottom bar dynamically updates as you write text, and contains the
possible names of modules or variables that are valid at that point
in the phrase you are entering. You can press the
<tab> key to complete the phrase with the
~/.ocamlinit file in your home directory
utop with common libraries and syntax
extensions so you don't need to type them in every time. Given
that you have Core installed, you should update your
ocamlinit to load Core every time you start
utop, by adding the following lines.
#use "topfind";; #thread;; #require "core.top";;
utop only you could get away with just the last
line, but you need the whole thing if you want the
ocaml toplevel to work too.
opam will have already added some lines
to the file. Also, notice that
# is used to mark a
toplevel directive, not a comment.
Editor set-upIn order to have a reasonable editing experience, there are a collection of different tools you'll want set up.
- An editor mode that understands the language, and can help with the basics of syntax-highlighting and navigation.
- Merlin, which provides out of your code, like auto-completion, go-to-definition, and type-throwback.
- ocp-indent, which auto-indents your code.
- ocamlformat, which provides fully automatic formatting and indentation (including line-breaking).
Visual Studio CodeThere are several OCaml modes for Visual Studio, but we recommend the OCaml Platform plug-in. This works alongside a server that supports the Visual Studio's Language Server Protocol (LSP). Instructions for installing OCaml LSP server can be found here. These instructions show you how to set things up so you can install the LSP server via opam. Eventually the LSP server will be available from opam by default.
Emacsopam comes with a
user-setuppackage that can be used to install Emacs configs. You can install it as follows. Note that we first make sure that
ocp-indent, an OCaml indentation tool, is available, as well as
tuareg, which is an Emacs mode for OCaml.
An alternative to
opam install tuareg ocp-indent merlin opam install user-setup opam user-setup install
ocamlformat, which is a full-on code formatter, as opposed to just an indenter.
ocamlformatyet, but you can find instructions here If you want fully automatic formatting (as opposed to just indentation), you should first install it via opam.
opam install ocamlformat
user-setupdoesn't support ocamlformat yet, but here are instructions for setting up ocamlformat for emacs.
Vim users can use the built-in style for handling OCaml source code. Beyond that, Merlin and other associated tools can be installed as follows.
If you want fully automatic formatting (as opposed to just indentation), you should first install it via opam.
opam install merlin ocp-indent opam install user-setup opam user-setup install
opam install ocamlformat
user-setupdoesn't support ocamlformat yet, but here are instructions for setting up ocamlformat for VIM.