On this page

OPAM Package Discovery, Installing Third-Party Libraries

Published on August 3, 2026

Enrico Hochkoeppler Profile

By Enrico Hochkoeppler

Web Developer & TutoriaLibre Founder

OCaml's standard library is deliberately small, which means almost every real project ends up depending on at least a handful of third-party packages — for JSON handling, testing, HTTP, concurrency, and countless other everyday needs. opam is the tool that manages those packages, and getting a dependency from "I found a promising-looking package" to "it's actually usable in my code" involves two separate steps: telling opam to install it, and telling Dune to link it into the build.

Finding Packages​

The community package repository is browsable directly at opam.ocaml.org's packages page, where each package lists its description, maintainers, dependencies, and version history. From the command line, opam list -a lists every package available in the currently configured repositories, and opam search <term> narrows that down to packages whose name or description matches a given term:


opam search json

Once a promising package has been found, opam show <package> prints its details directly in the terminal — its synopsis, homepage, dependencies, and available versions — without needing to install anything first:


opam show yojson

This is worth doing before installing anything new, since it surfaces a package's own dependencies and constraints up front, rather than discovering them only after the fact.

Quick, Exploratory Installation​

For simply trying a library out, opam install <package> installs it directly into whichever switch is currently active:


opam install yojson

This is fast and genuinely useful for experimentation, but it has a real limitation: nothing about this installation is recorded anywhere in the project itself. A collaborator who clones the project, or a continuous integration pipeline building it from scratch, has no way of knowing this dependency exists, since it lives only in one particular switch on one particular machine.

The Reproducible Way: Declaring Dependencies in dune-project​

For anything beyond quick experimentation, a dependency belongs in the project's dune-project file, inside its package metadata, using a depends field:


(lang dune 3.0)

(name my_project)



(package

 (name my_project)

 (depends

  (ocaml (>= 4.14))

  dune

  (yojson (>= 2.0))

  (alcotest (and (>= 1.7) :with-test))))

Each dependency can carry a version constraint, written in parentheses right after its name — (yojson (>= 2.0)) requires at least version 2.0. The :with-test tag marks a dependency, like alcotest here, as only needed when running the project's test suite, not for an ordinary build; a corresponding :with-doc tag exists for dependencies only needed when generating documentation. Dune uses this depends field to automatically generate the project's .opam file, which is the format opam itself actually reads.

With the dependency declared this way, running:


opam install . --deps-only

tells opam to look at the current directory's .opam file and install whatever it's missing to satisfy every listed dependency, bringing the active switch in line with what the project actually declares. Adding --with-test or --with-doc to that command additionally installs the dependencies tagged for testing or documentation, which are otherwise skipped by default:


opam install . --deps-only --with-test --with-doc

This is the version of "installing a dependency" that's actually reproducible: anyone who clones the project can run the exact same command and end up with a switch capable of building it, since the list of what's needed lives in the project itself rather than in one person's local environment.

Actually Using the Library in Code​

Declaring a dependency with opam makes it available to install, but a package still needs to be added to the relevant dune file's libraries field before any code can actually use it — opam and Dune handle two different, complementary jobs, the former managing what's installed, the latter managing what's linked into a given build target.


(executable

 (name main)

 (libraries yojson))

With both pieces in place — the dependency declared in dune-project, installed into the switch, and referenced in the relevant dune file — Yojson becomes available to open or qualify directly inside the project's source files.

Installing From Git for Unreleased Packages​

Occasionally, a needed package isn't published on the official repository yet, or a specific unreleased fix is needed directly from its source repository. For this situation, an <project>.opam.template file, alongside a pin-depends entry, tells opam to build a dependency directly from a Git source rather than from the standard package repository, while keeping that pin recorded in the project itself rather than only in one developer's local opam configuration. This is a more advanced, situational technique — most day-to-day dependencies are available directly from the standard repository and don't need it.

Key Takeaways​

Found this helpful? Share the knowledge...

... or support this project to keep it alive!

Buy Me a Coffee

Previous

Dune Deep Dive

Next

Unit Testing