Running Commands in an opam Switch

Opam is a package manager for OCaml that facilitates the installation and management of OCaml libraries and tools. When working with opam, it's essential to understand how to run commands within a specific opam switch. In this tutorial, we'll explore three methods: opam env, opam exec, and direnv.

Using opam env

The opam env command is used to set environment variables for a specific opam switch. This method is useful for configuring your shell environment to work with a particular opam switch.


$ eval $(opam env)

This command evaluates the output of opam env and sets the necessary environment variables for the currently active switch. After running this command, you'll have access to the packages installed in the opam switch.

Using opam exec

The opam exec command allows you to run a command in the context of a specific opam switch without modifying your shell environment.


$ opam exec -- <command>

Replace <command> with the actual command you want to run. This ensures that the command is executed within the opam switch's environment.


$ opam exec -- ocaml

This will launch the version of the OCaml REPL within the context of the current opam switch.

Using direnv

Direnv is a tool (written in Go) that allows you to set environment variables based on your current directory. It is especially useful for managing opam switches and automating the setup of project-specific environments.

  1. Install direnv

Ensure direnv is installed on your system. You can install it using a package manager or follow the instructions on the official website.

  1. Setup direnv integration

Add the following line to your shell profile (e.g., ~/.bashrc or ~/.zshrc):

$ eval $(direnv hook <shell>)

Replace <shell> with your actual shell type (bash, zsh, fish, etc.).

  1. Configure opam with direnv

In your OCaml project directory, create a file named .envrc and add the following line to automatically load the opam environment:

eval $(opam env)
  1. Allow direnv

Navigate to your project directory and run the following command to allow direnv to load the environment:

$ direnv allow

This command activates direnv for the current directory, ensuring that the opam switch environment is loaded whenever you enter the directory.

  1. Usage

Now, whenever you navigate to your OCaml project directory, direnv will automatically activate the opam switch environment specified in your .envrc file. This eliminates the need to manually run opam env each time you work on your project.

  1. Example

Suppose you have an OCaml project in folder disco and local opam switch is associated to it, and a .envrc file in that folder containing the following:

eval $(opam env)

After running direnv allow, direnv will handle the opam switch activation for you.

  1. Messages from direnv

Whenever entering or leaving a direnv managed folder, you will be informed of the the actions performed.

On entrance:

direnv: loading ~/caml/

On exit:

direnv: loading ~/.envrc
direnv: export ~PATH

By using direnv in conjunction with opam, you can streamline your development workflow, ensuring that the correct opam switch is automatically set up whenever you work on a specific project.

Help Improve Our Documentation

All OCaml docs are open source. See something that's wrong or unclear? Submit a pull request.