- Courses
- 💻Programming Languages
- 🐫OCaml (WIP)
- Modules, Structure & Tooling
- OPAM Package Discovery & Installation
On this page
OPAM Package Discovery, Installing Third-Party Libraries
Published on August 3, 2026
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
opam search,opam list -a, andopam showare the tools for discovering and inspecting packages before installing anything.opam install <package>is fast for experimentation, but installs only into the local switch, with no record left in the project itself.- Declaring a dependency in
dune-project'sdependsfield, with an optional version constraint and:with-test/:with-doctags where appropriate, is what makes a dependency reproducible for every collaborator and CI pipeline. opam install . --deps-only(optionally with--with-testand--with-doc) installs exactly what a project's own declared dependencies require.- A dependency has to be both installed through opam and added to the relevant
dunefile'slibrariesfield before any code can actually use it — the two tools handle separate, complementary responsibilities. - Packages not yet published to the standard repository can be pulled directly from a Git source using an
.opam.templatefile andpin-depends, though this is a situational technique rather than the everyday path.
Found this helpful? Share the knowledge...
... or support this project to keep it alive!
Previous
Dune Deep Dive
Next
Unit Testing
- Finding Packages
- Quick, Exploratory Installation
- The Reproducible Way: Declaring Dependencies in dune-project
- Actually Using the Library in Code
- Installing From Git for Unreleased Packages
- Key Takeaways
