OCaml Package Management Tools

Managing OCaml packages effectively depends on your workflow and environment. The current standard is OPAM (OCaml Package Manager), which handles dependency resolution, version switching, and sandboxed environments.

OPAM: The Standard Choice

OPAM is the de facto package manager for OCaml and is maintained by the OCaml community. Install it using your system package manager or from source:

# Ubuntu/Debian
sudo apt install opam

# Fedora/RHEL
sudo dnf install opam

# macOS
brew install opam

For other distributions, download the binary or build from source:

wget https://github.com/ocaml/opam/releases/download/2.1.5/opam-2.1.5-x86_64-linux
chmod +x opam-2.1.5-x86_64-linux
sudo mv opam-2.1.5-x86_64-linux /usr/local/bin/opam

After installation, initialize OPAM:

opam init

This sets up your OPAM environment and adds initialization code to your shell configuration. Verify the setup with:

eval $(opam env)

Core OPAM Commands

List available packages and search:

opam list                    # Show installed packages
opam list --available        # Show all packages in the repository
opam search QUERY            # Search by name or description
opam show PACKAGE            # Display package details

Update your package database and install packages:

opam update                  # Sync with upstream repositories
opam install PACKAGE         # Install a package with dependencies
opam install PACKAGE.VERSION # Install a specific version
opam remove PACKAGE          # Uninstall a package
opam upgrade                 # Upgrade all installed packages

OCaml Version Switching

OPAM tracks OCaml compiler versions as “switches.” This allows you to maintain multiple isolated OCaml environments:

opam switch list             # Show available OCaml versions
opam switch create 5.1.1     # Create an environment with OCaml 5.1.1
opam switch 5.1.1            # Activate a switch
eval $(opam env)             # Load the switch environment

Each switch is independent—packages installed in one switch don’t affect others. This is useful for testing across compiler versions or maintaining legacy projects.

Dune: The Build System

While OPAM manages dependencies, Dune has become the standard build system for OCaml projects. Install it via OPAM:

opam install dune

Dune handles compilation, linking, and testing. Create a dune-project file in your project root to mark it as a Dune project, and organize code with dune files in each directory.

Opam Monorepos and Workspaces

For projects with multiple interdependent packages, use OPAM’s monorepo workflow:

opam pin add PACKAGE /path/to/local/package
opam install --with-test PACKAGE  # Install with test dependencies

This pins local packages for development while managing external dependencies through OPAM.

Useful Configuration

Set your default shell environment by adding to ~/.bashrc or ~/.zshrc:

eval $(opam env)

For direnv users, create a .envrc file in your project:

use opam

This automatically activates the correct OPAM switch when entering the directory.

Recovery and Troubleshooting

If you accidentally delete your OPAM directory, reinitialize from scratch:

opam init --reinit
opam switch create 5.1.1  # Choose your desired compiler version

Check OPAM’s status with:

opam switch show            # Current active switch
opam var prefix             # OPAM installation root
opam config report          # Full diagnostics

When to Use Containers

For reproducible builds across systems, combine OPAM with Docker. Use official OCaml images as base:

FROM ocaml/ocaml:5.1
RUN opam install dune
COPY . /app
WORKDIR /app
RUN eval $(opam env) && dune build

This ensures consistent environments and is the recommended approach for CI/CD pipelines.