Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 40 ยท Getting Started

Installing OCaml with opam

Install OCaml the standard way: set up opam, create a switch, add dune, utop and the language server, and check that everything works on Linux, macOS and Windows.

The standard way to install OCaml is through opam, the OCaml package manager. Opam installs compilers, libraries and tools, and it keeps several versions side by side in isolated environments called switches. This lesson walks you through the setup and the handful of commands you will use all the time.

You cannot run these commands on this site, so every block is read-only. Copy them into your own terminal. Output shown is typical; version numbers will differ on your machine.

Step 1: install opam

macOS (with Homebrew):

Terminal
brew install opam

Debian, Ubuntu and relatives:

Terminal
sudo apt install opam

Other Linux distributions and macOS without Homebrew: the opam project provides an install script on its website; most distributions also package opam directly (pacman -S opam, dnf install opam, and so on).

Windows: the easiest route is the official Windows installer for opam, which sets up a native OCaml environment. Alternatively, install WSL (Windows Subsystem for Linux), open an Ubuntu terminal and follow the Linux steps. Both work; WSL behaves exactly like the Linux instructions in most tutorials.

Step 2: initialize opam

Run this once per machine:

Terminal
opam init

Opam downloads the package list and creates ~/.opam. It offers to update your shell profile so that opam's tools are on your PATH; say yes. Then load the environment into your current terminal:

Terminal
eval $(opam env)

You normally do this once in each new terminal, unless your shell profile does it automatically.

Step 3: create a switch

A switch is an independent set of installed packages with its own compiler. opam init usually creates a default one. To create a named switch with a specific compiler:

Terminal
opam switch create learn 5.3.0
eval $(opam env --switch=learn)

The name learn is arbitrary, and 5.3.0 is a compiler version; pick a recent 5.x release (opam switch list-available shows what exists). To see what you have:

Terminal
opam switch list
ocaml -version

The second command prints something like The OCaml toplevel, version 5.3.0.

Step 4: install the everyday tools

Terminal
opam install dune utop ocaml-lsp-server ocamlformat
Package What it gives you
dune The build system: compiles projects, runs tests
utop A friendly interactive toplevel (REPL)
ocaml-lsp-server The language server for editors (completion, types on hover)
ocamlformat An automatic code formatter

Opam builds these from source the first time, so it can take a few minutes. Afterwards, dune --version and utop should both work.

Step 5: set up your editor

  • VS Code: install the extension called "OCaml Platform". It uses ocaml-lsp-server, shows types when you hover, and formats on save with ocamlformat.
  • Vim and Neovim, Emacs, Helix, Zed: all speak the language server protocol; point them at ocamllsp.

If your editor says it cannot find ocamllsp, it is almost always because the editor was started in a terminal where eval $(opam env) had not been run. Launch the editor from a terminal after loading the opam environment.

Checking the install

Create a file hello.ml with one line:

OCAML
let () = print_endline "It works"

Then compile and run it two ways:

Terminal
ocaml hello.ml
TEXT
It works

This runs the file with the interpreter. The compiler way produces a real executable:

Terminal
ocamlfind ocamlopt hello.ml -o hello
./hello

You will rarely call ocamlopt by hand. In the next lesson you will use dune, which does it for you.

Useful opam commands

Terminal
opam update                 # refresh the package list
opam upgrade                # upgrade installed packages
opam search json            # find packages by keyword
opam install yojson         # install a library
opam list                   # show what is installed in this switch
opam switch remove learn    # delete a switch

The mental model: opam installs things into a switch, dune builds your project using what is in the current switch. If a library cannot be found by dune, you usually forgot opam install or you are in the wrong switch.

A stand-in: modelling switches

If you know JavaScript, a switch is like a separate node_modules plus a Node version. The stand-in below models the idea: each switch has its own compiler and packages, and installing into one does not affect the other.

JS Stand-in: switches keep packages separate

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is opam?

    opam installs OCaml compilers and libraries and manages isolated switches.
  2. 2. What is an opam switch?

    Switches let you keep several compiler versions and package sets side by side.
  3. 3. Which package is the standard OCaml build system?

    dune builds projects; utop is a REPL, ocamlformat a formatter and yojson a JSON library.
  4. 4. Why should you run eval $(opam env)?

    The command sets environment variables so that the shell finds the compiler and tools of the active switch.

Summary

  • Install opam, run opam init, and load the environment with eval $(opam env).
  • Create a switch with a recent 5.x compiler, then install dune, utop, ocaml-lsp-server and ocamlformat.
  • On Windows, use the official opam installer or WSL.
  • Packages go into switches; dune builds against the current switch.

Next: Your first program with dune