Introduction to opam

Install the binary. On macOS via Homebrew, on Debian/Ubuntu via apt.

$ brew install opam
$ apt install opam

First-time setup: clones opam-repository and creates a default switch.

$ opam init

Put the active switch's binaries on PATH for this shell. opam init offers to add this to your shell profile; if you declined, run it yourself.

$ eval $(opam env)

Confirm which compiler you are actually running.

$ ocaml -version
The OCaml toplevel, version 5.2.0

List the compiler versions available to install.

$ opam switch list-available

Create a named global switch on a specific compiler.

$ opam switch create 5.2.0

Create a local switch for the project in the current directory. The trailing dot is the directory, not the version.

$ opam switch create . 5.2.0
creates ./_opam

Create a switch with compiler variants enabled - flambda for aggressive inlining, or the sanitizers.

$ opam switch create 5.2.0+flambda ocaml-variants.5.2.0+options ocaml-option-flambda

See every switch, with an arrow on the active one.

$ opam switch list

Switch to another one, then re-evaluate the environment. The env step is not optional - without it your shell still points at the previous compiler.

$ opam switch set 5.1.1
$ eval $(opam env)

Run a single command under a different switch without changing the active one.

$ opam exec --switch=5.1.1 -- dune build

Delete a switch and everything installed into it.

$ opam switch remove 5.1.1

Refresh the package metadata. Do this before complaining that a newly released version is missing.

$ opam update

Search by name or description.

$ opam search json

Read a package's description, dependencies, and available versions.

$ opam show yojson

Install one or more packages into the active switch.

$ opam install yojson lwt

Install a specific version.

$ opam install yojson.2.1.2

List what is installed in the active switch.

$ opam list

List only the packages you asked for, rather than every transitive dependency.

$ opam list --installed-roots

Upgrade everything the solver can move forward.

$ opam upgrade

Upgrade a single package and whatever it drags along.

$ opam upgrade yojson

Remove a package.

$ opam remove yojson

Remove a package along with dependencies nothing else needs any more.

$ opam remove --auto-remove yojson

In dune-project: declare the package and its dependencies, with version bounds where they matter.

$ (lang dune 3.16)
$ (generate_opam_files true)
$  
$ (package
$  (name hello)
$  (synopsis "An example")
$  (depends
$   (ocaml (>= 4.14))
$   dune
$   yojson
$   (alcotest :with-test)))

Regenerate hello.opam after editing that stanza.

$ dune build

Install every dependency listed by the .opam files in this directory, including test-only ones.

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

The usual first two commands in a fresh clone: a local switch, then its dependencies.

$ opam switch create . 5.2.0 --no-install
$ opam install . --deps-only --with-test --with-doc

Ask why a package is installed - which of your roots pulled it in.

$ opam list --required-by yojson
$ opam list --depends-on yojson

Pin a dependency to a local checkout you are editing.

$ opam pin add yojson ../yojson

Pin to a git branch or tag.

$ opam pin add yojson git+https://github.com/ocaml-community/yojson.git#master

Record the pin but do not build it yet - useful when you are about to pin several things and want one solver run at the end.

$ opam pin add --no-action yojson ../yojson
$ opam install yojson

Re-read a local pin after you have changed its source. Pins are not watched.

$ opam upgrade yojson

See what is pinned, and undo it.

$ opam pin list
$ opam unpin yojson

Show the plan without carrying it out.

$ opam install lwt --dry-run

Ask for a solution that leaves existing packages alone where possible, or the opposite - let it upgrade whatever it needs.

$ opam install lwt --criteria="-removed,-changed"
$ opam install lwt --unlock-base

Check whether the switch is currently consistent.

$ opam install --check
$ opam lint hello.opam

Reinstall a package from scratch when a build left something half-written.

$ opam reinstall yojson

Clear the download and build caches. This one is a real fix more often than it should be.

$ opam clean -a

Export the exact package set of the active switch.

$ opam switch export switch.export

Recreate that package set somewhere else - another machine, or CI.

$ opam switch import switch.export

Include the source of pinned packages in the export, so the import does not depend on those URLs still resolving.

$ opam switch export --full switch.export

Check the package file against the repository's rules before anyone else does.

$ opam lint hello.opam

Build a release tarball and the opam file that points at it.

$ dune-release tag
$ dune-release distrib

Open the pull request against opam-repository.

$ dune-release publish
$ dune-release opam pr

Or do the submission step alone, from an existing tag and archive URL.

$ opam publish https://github.com/you/hello/archive/v1.0.0.tar.gz

Add a second repository to the active switch, at higher priority than the default.

$ opam repository add mine https://example.com/opam --rank=1

Add one globally, so every new switch picks it up.

$ opam repository add mine https://example.com/opam --all-switches

List repositories and their order.

$ opam repository list

Remove one.

$ opam repository remove mine