OPAM-SWITCH(1)

📦
version 2.6.1 · 8 versions
, in arch rolling, fedora 44

✨ NAME ✨

opam-switch — the one that manages multiple installation prefixes 💅 (this is part of the Opam Manual, bestie, so you know it's official)

🦋 SYNOPSIS 🦋

opam switch [OPTION]… [COMMAND] [ARG]…

🌸 DESCRIPTION 🌸

Okay so, this command is literally the switch manager. A "switch" is an independent installation prefix — it's got its own compiler, its own set of installed packages, and its own set of pinned packages. Nothing bleeds between them, which is the whole point. The classic use case: you want different versions of the compiler hanging around at the same time. Iconic. 👑

Use opam switch create to create a new switch, and opam switch set to set the currently active one. With no argument at all, it just lists your installed switches. With exactly one switch argument, it defaults to set. Periodt.

Now, whenever you see SWITCH in this page, it can be either of these two things:

  • a plain name, for switches that live inside ~/.opam, or
  • a directory name — and in that case, that directory is where the switch prefix gets installed, as _opam.

Opam will automatically pick a switch by that name if it finds one in the current directory or any of its parents — unless OPAMSWITCH is set or you passed --switch. And oh, when you're creating a directory switch, if there are package definitions sitting locally, the user gets automatically prompted to install them right after the switch is created. Unless you passed --no-install. 🙈

opam switch set sets the default switch globally. The shell hook, when it's enabled, keeps your current shell session in sync with that switch — unless the current directory is a local switch, in which case that local switch wins instead. And you can always use eval $(opam env --switch=SWITCH --set-switch) to name the switch explicitly, which overrides the shell hook. No cap.

💫 COMMANDS 💫

With no argument, it defaults to list.

SWITCH

With a SWITCH argument, this defaults to set SWITCH.

-

Switches back to the previous non-local switch (basically like git switch -). If you actually want to set the current switch to a switch literally named -, then you gotta use --cli=2.1 or lower, or use opam switch set -.

create SWITCH [COMPILER]

Create a new switch, and install the given compiler in it. SWITCH can be a plain name, or a directory — absolute or relative — and in that case a local switch gets created below the given directory. COMPILER, if you leave it out, defaults to SWITCH when it's a plain name — unless you passed --packages, --formula or --empty.

When you're creating a local switch and none of those options are present, the compiler gets chosen according to the configuration default (peep opam-init(1) for that). And if the directory you chose contains package definitions, a compatible compiler is searched within the default selection, and the packages will automatically get installed. Slay. ✨

set SWITCH

Set the currently active switch, from among the installed switches.

remove SWITCH

Removes that switch from disk. Bye bestie 👋

export FILE

Save the current switch state to a file. If --full is specified, it includes the metadata of all installed packages, and if --freeze is specified, it freezes all vcs to their current commit.

import FILE

Import a saved switch state. If --switch is specified and doesn't point to an existing switch, the switch will be created just for the import. Cute.

reinstall [SWITCH]

Reinstall the given compiler switch and all its packages.

list

Lists installed switches. That's it, that's the whole job. 💅

list-available [PATTERN]

Lists all the possible packages that are advised for installation when creating a new switch — i.e. packages with the compiler flag set. If no pattern is supplied, all versions are shown. By default, packages flagged with avoid-version or deprecated will not appear unless you give --all.

show

Prints the name of the current switch.

invariant

Prints the active switch invariant.

set-invariant PACKAGES

Updates the switch invariant — which is, like, the formula that the switch must keep verifying throughout all operations. The previous setting gets overridden. See also the options --force and --no-action. With no arguments, an invariant is just chosen automatically.

set-description STRING

Sets the description for the selected switch.

Sets a local alias for a given switch, so the switch gets automatically selected whenever you're in that directory or any descendant of it. Handy fr fr.

install SWITCH

Removed in 2.1. Use create instead.

set-base PACKAGES

Removed in 2.1. Use set-invariant instead.

🎀 EXAMPLES 🎀

opam switch create 4.08.0

Create a new switch called 4.08.0 and select it, with a compiler automatically selected at version 4.08.0 (note that this can fail in case there is more than one compiler matching that version).

opam switch create ./ --deps-only

Prepare a local switch for building the packages defined in ./. This scans the current directory for package definitions, chooses a compatible compiler, creates a local switch and installs the local package dependencies.

opam switch create trunk --repos default,beta=https://github.com/ocaml/ocaml-beta-repository.git ocaml-variants.4.10.0+trunk

Create a new switch called trunk, with ocaml-variants.4.10.0+trunk as compiler, with a new beta repository bound to the given URL selected besides the default one.

🔥 OPTIONS 🔥

  • -A COMP, --alias-of=COMP — Removed in 2.1. 💀
  • --all — Only for list-available: show all available compilers, regardless of whether they are flagged with avoid-version or deprecated.
  • --deps-only — When creating a local switch in a project directory (i.e. a directory containing opam package definitions), install the dependencies of the project but not the project itself. When importing a switch, do not install root packages.
  • --description=STRING — Attach the given description to a switch when creating it. Use the set-description subcommand to modify the description of an existing switch.
  • --empty — Allow creating an empty switch, with no invariant.
  • --force — Only for set-invariant: force setting the invariant, bypassing consistency checks.
  • --formula=FORMULA — Lets you specify a complete "dependency formula", possibly including disjunction cases, as the switch invariant. The format is the same as for expressing dependencies in package definition files, e.g. '"foo" {>= "1.1"}'
  • --freeze — When exporting, locks all VCS urls to their current commit, failing if it can not be retrieved. This ensures that an import will restore the exact state. Implies --full.
  • --full — When exporting, include the metadata of all installed packages, allowing you to re-import even if they don't exist in the repositories (the default is to include only the metadata of pinned packages).
  • -n, --no-action — Only for set-invariant: set the invariant, but don't enforce it right away — wait for the next install, upgrade or similar command.
  • --no-autoinstall — Removed in 2.1. 💀
  • --no-install — When creating a local switch, don't look for any local package definitions to install.
  • --no-switch — Don't automatically select newly installed switches.
  • --packages=PACKAGES — When installing a switch, explicitly define the set of packages to enforce as the switch invariant.
  • --repositories=REPOS — When creating a new switch, use the given selection of repositories instead of the default. REPOS should be a comma-separated list of either already registered repository names (configured through e.g. opam repository add --dont-select), or NAME=URL bindings — in which case NAME should not be registered already to a different URL, and the new repository will be registered. See opam repository for more details. This option also affects list-available.
  • -s, --short — Output raw lists of names, one per line, skipping any details.

🛠️ PACKAGE BUILD OPTIONS 🛠️

okay bestie this is the section where opam gets ✨opinions✨ about how your packages actually get built. buckle up 🎀

  • --assume-depexts — skips the whole "install your missing system packages" step and just yolo-tries to compile the opam packages anyway. if it works out, opam will never nag you about those system packages again 🫶. only does anything when external dependency handling is turned on, so don't expect magic otherwise.
  • -b, --keep-build-dir — keeps the build directories around after compiling. literally the same thing as setting $OPAMKEEPBUILDDIR to "true". hoarder energy, we respect it 💅
  • --build-doc — bestie. this got removed in 2.1. use --with-doc instead, okay? don't be out here using the fossilized flag 😭
  • --build-test — also removed in 2.1 💀 use --with-test instead. same deal, same vibe, new name.
  • -d, --with-doc — builds the package docs 📚. heads up: this only touches packages you actually listed on the command-line. same as setting $OPAMWITHDOC (or the deprecated $OPAMBUILDDOC) to "true".
  • --dry-run — simulates the command but doesn't actually change anything. a rehearsal, a dress run, no consequences 🌸. can also be set with the environment variable $OPAMDEBUG.
  • --fake — registers actions into the opam database without actually doing them. WARNING: this one is dangerous and is likely to break your opam environment 💀💀. you probably want --dry-run instead. you've been warned, bestie, don't come crying to me.
  • --ignore-available-on[=PACKAGES] (default=) — forces opam to mark the listed packages as available. great for testing compatibility, but fr fr expect builds to break when you use this 🙈. note that version constraints of the packages' dependencies are unaffected.
  • --ignore-constraints-on[=PACKAGES] (default=) — forces opam to ignore version constraints on all dependencies of the listed packages. again: compatibility testing tool, and again: expect builds to break 😭. note that the availability of the packages, plus version constraints on optional dependencies and conflicts, are all unaffected. same as setting $OPAMIGNORECONSTRAINTS.
  • --inplace-build — when a package's source is bound to a local directory, does the build and install actions directly in that directory instead of in a clean copy that opam handles. only affects packages explicitly listed on the command-line. same as setting $OPAMINPLACEBUILD to "true". gettin' cozy in there 🏠
  • -j JOBS, --jobs=JOBS — sets the max number of concurrent jobs. default is calculated from your core count 🔥. you can also set this with the $OPAMJOBS environment variable.
  • --lock-suffix=SUFFIX (absent=locked) — sets the locked files suffix to SUFFIX.
  • --locked — in commands that use opam files found from pinned sources, if a variant of the file with an added .locked extension exists (like foo.opam.locked sitting right next to foo.opam), then that one gets used instead 👑. this is usually for offering a more specific set of dependencies and reproducing similar build contexts — hence the name, iykyk. the lock option can generate such files based on the versions of the dependencies currently installed on your host. same as setting the $OPAMLOCKED environment variable. note that this option doesn't generally affect packages that are already pinned.
  • -m MAKE, --make=MAKE — removed in 2.1. use opam config set[-global] make MAKE instead, bestie ✨
  • --no-checksums — do not verify the checksum of downloaded archives. same as setting $OPAMNOCHECKSUMS to "true".
  • --no-depexts — temporarily disables handling of external dependencies. useful when a package isn't available through your system package manager but you installed the needed dependency by hand 🙌. this implies --assume-depexts, and it also stores the exceptions upon success. two-for-one, no cap.
  • --require-checksums — rejects installation of packages that don't provide a checksum for the upstream archives. same as setting $OPAMREQUIRECHECKSUMS to "true". strict queen behavior 👑
  • --reuse-build-dir — reuses existing build directories (the ones you kept by using --keep-build-dir) instead of compiling from a fresh clone of the source. can be faster, but it can also lead to failures if the build systems of the packages don't handle upgrades of dependencies well. same as setting $OPAMREUSEBUILDDIR to "true".
  • --show-actions — calls the solver and displays the actions. performs no changes. same as setting $OPAMSHOW. a peek, not a touch 👀
  • --skip-updates — when running an install, upgrade or reinstall on source-pinned packages, they normally get updated from their origin first. this flag disables that behavior and keeps them at their version in cache. same as setting $OPAMSKIPUPDATE.
  • -t, --with-test — builds and runs the package unit-tests 🧪. only affects packages listed on the command-line. same as setting $OPAMWITHTEST (or the deprecated $OPAMBUILDTEST) to "true".
  • --unlock-base — removed in 2.1. use --update-invariant instead 💅
  • --update-invariant — allows changes to the packages set as switch base (typically, the main compiler). use with caution ⚠️. same as setting the $OPAMUNLOCKBASE environment variable.
  • --verbose-on=PACKAGES — be more verbose on specific packages. same as setting $OPAMVERBOSE.
  • --with-dev-setup — include development tools only dependencies.

✨ COMMON OPTIONS ✨

okay bestie, these are the common options — the ones every command shares. like, universal vibes. no cap. 💖

  • --best-effort — Don't fail if all requested packages can't be installed: try to install as many as possible. Note that not all external solvers may support this option (recent versions of aspcud or mccs should). This is equivalent to setting the $OPAMBESTEFFORT environment variable. manifesting a partial win ✨
  • --cli=MAJOR.MINOR (absent=2.6) — Use the command-line interface syntax and semantics of MAJOR.MINOR. Intended for any persistent use of opam (scripts, blog posts, etc.), any version of opam in the same MAJOR series will behave as for the specified MINOR release. The flag was not available in opam 2.0, so to select the 2.0 CLI, set the OPAMCLI environment variable to 2.0 instead of using this parameter. time travel but make it CLI 🕰️
  • --color=WHEN — Colorize the output. WHEN must be one of always, never or auto. aesthetic choices matter 🌈
  • --confirm-level=LEVEL — Confirmation level, LEVEL must be one of ask, no, yes or unsafe-yes. Can be specified more than once. If --yes or --no are also given, the value of the last --confirm-level is taken into account. This is equivalent to setting $OPAMCONFIRMLEVEL. choose your own adventure 🎀
  • --criteria=CRITERIA — Specify user preferences for dependency solving for this run. Overrides $OPAMCRITERIA, $OPAMFIXUPCRITERIA and $OPAMUPGRADECRITERIA. For details on the supported language, and the external solvers available, see http://opam.ocaml.org/doc/External_solvers.html. A general guide to using solver preferences can be found at http://www.dicosmo.org/Articles/usercriteria.pdf. solver taste, but make it yours 💅
  • --cudf=FILENAME — Debug option: Save the CUDF requests sent to the solver to FILENAME-<n>.cudf where <n> is the n-th call to the solver during the opam run. receipts, but for the solver 🧾
  • --debug — Print debug message to stderr. This is equivalent to setting $OPAMDEBUG to "true". yell it out 📢
  • --debug-level=LEVEL — Like --debug, but allows specifying the debug level (--debug sets it to 1). Equivalent to setting $OPAMDEBUG to a positive integer. dial the chaos up 🔥
  • --git-version — Print the git version of opam, if set (i.e. you are using a development version), and exit. dev build girlies rise 🛠️
  • --help[=FMT] (default=auto) — Show this help in format FMT. The value FMT must be one of auto, pager, groff or plain. With auto, the format is pager or plain whenever the TERM env var is dumb or undefined. help is help, bestie 🫶
  • --ignore-pin-depends — Ignore extra pins required by packages that get pinned, either manually through opam pin or through opam install DIR. This is equivalent to setting IGNOREPINDEPENDS=true. mind your business, pins 🙈
  • --json=FILENAME — Save the results of the opam run in a computer-readable file. If the filename contains the character %, it will be replaced by an index that doesn't overwrite an existing file. Similar to setting the $OPAMJSON variable. machine-readable slay 🤖
  • --no — Answer no to all opam yes/no questions without prompting. See also --confirm-level. This is equivalent to setting $OPAMNO to "true". nope, not today 💀
  • --no-aspcud — Removed in 2.1. rip bozo 💀
  • --no-auto-upgrade — When configuring or updating a repository that is written for an earlier opam version (1.2), opam internally converts it to the current format. This disables this behaviour. Note that repositories should define their format version in a 'repo' file at their root, or they will be assumed to be in the older format. It is, in any case, preferable to upgrade the repositories manually using opam admin upgrade [--mirror URL] when possible. do it by hand if you can, bestie 🧼
  • --no-self-upgrade — Opam will replace itself with a newer binary found at OPAMROOT/opam if present. This disables this behaviour. stay in your lane, opam 🚫
  • -q, --quiet — Disables --verbose. shhh 🤫
  • --root=ROOT — Use ROOT as the current root path. This is equivalent to setting $OPAMROOT to ROOT. new home, who dis 🏠
  • --safe, --readonly — Make sure nothing will be automatically updated or rewritten. Useful for calling from completion scripts, for example. Will fail whenever such an operation is needed ; also avoids waiting for locks, skips interactive questions and overrides the $OPAMDEBUG variable. This is equivalent to set environment variable $OPAMSAFE. look but don't touch 👀
  • --solver=CMD — Specify the CUDF solver to use for resolving package installation problems. This is either a predefined solver (this version of opam supports builtin-mccs+lp(), builtin-mccs+glpk, builtin-dummy-z3-solver, builtin-0install, aspcud, mccs, aspcud-old, packup), or a custom command that should contain the variables %{input}%, %{output}%, %{criteria}%, and optionally %{timeout}%. This is equivalent to setting $OPAMEXTERNALSOLVER. choose your fighter ⚔️
  • --strict — Fail whenever an error is found in a package definition or a configuration file. The default is to continue silently if possible. no more sweeping under the rug 🧹
  • --switch=SWITCH — Use SWITCH as the current compiler switch. This is equivalent to setting $OPAMSWITCH to SWITCH. switch it up 🔄
  • --use-internal-solver — Disable any external solver, and use the built-in one (this requires that opam has been compiled with a built-in solver). This is equivalent to setting $OPAMNOASPCUD or $OPAMUSEINTERNALSOLVER. homegrown solver moment 🌱
  • -v, --verbose — Be more verbose. One -v shows all package commands, repeat to also display commands called internally (e.g. tar, curl, patch etc.) Repeating n times is equivalent to setting $OPAMVERBOSE to "n". say it louder for the people in the back 📣
  • --version — Show version information. who am i? you're opam, bestie 💖
  • -w, --working-dir — Whenever updating packages that are bound to a local, version-controlled directory, update to the current working state of their source instead of the last committed state, or the ref they are pointing to. As source directory is copied as it is, if it isn't clean it may result on a opam build failure. This only affects packages explicitly listed on the command-line. It can also be set with $OPAMWORKINGDIR. use the messy current you 🌀
  • -y, --yes — Answer yes to all opam yes/no questions without prompting. See also --confirm-level. This is equivalent to setting $OPAMYES to "true". yes queen, install everything 👑

🌸 ENVIRONMENT 🌸

okay so opam is lowkey obsessed with environment variables, and honestly? here's the entire roster, bestie. but first, the one rule you cannot fumble: the boolean ones want "0", "no", "false" or the empty string to be turned off, and "1", "yes" or "true" to be turned on. that's the whole vibe, no cap. ✨

  • OPAMALLPARENS — surround all filters with parenthesis. yep, all of them. 💅
  • OPAMASSUMEDEPEXTS — see the option --assume-depexts.
  • OPAMAUTOANSWER — internal use only 🙈 (not for you, bestie).
  • OPAMAUTOREMOVE — see the remove option --auto-remove.
  • OPAMBESTEFFORT — see the option --best-effort.
  • OPAMBESTEFFORTPREFIXCRITERIA — sets the string that must be prepended to the criteria when the --best-effort option is set, and is expected to maximise the opam-query property in the solution.
  • OPAMBUILDDOC — Removed in 2.1. 💀 gone, periodt.
  • OPAMBUILDTEST — Removed in 2.1. 💀 also gone.
  • OPAMCLI — see the option --cli.
  • OPAMCOLOR — when set to always or never, sets a default value for the --color option.
  • OPAMCONFIRMLEVEL — see the option --confirm-level. OPAMCONFIRMLEVEL has priority over OPAMYES and OPAMNO. 👑 (it's the main character here.)
  • OPAMCRITERIA — specifies user preferences for dependency solving. the default value depends on the solver version, so use config report to know the current setting. see also the option --criteria.
  • OPAMCUDFFILE — save the cudf graph to file-actions-explicit.dot.
  • OPAMCUDFTRIM — controls the filtering of unrelated packages during CUDF preprocessing.
  • OPAMCURL — can be used to select a given 'curl' program. see OPAMFETCH for more options.
  • OPAMDEBUG — see the options --debug and --debug-level.
  • OPAMDEBUGSECTIONS — if set, limits debug messages to the space-separated list of sections. sections can optionally have a specific debug level (for example, CLIENT:2 or CLIENT CUDF:2), but otherwise use --debug-level.
  • OPAMDIGDEPTH — defines how aggressive the lookup for conflicts during CUDF preprocessing is.
  • OPAMDOWNLOADJOBS — sets the maximum number of simultaneous downloads.
  • OPAMDROPWORKINGDIR — overrides packages previously updated with --working-dir on update. without this variable set, opam would keep them unchanged unless they're explicitly named on the command-line.
  • OPAMDRYRUN — see the option --dry-run.
  • OPAMEDITOR — sets the editor to use for opam file editing, and it overrides $EDITOR and $VISUAL.
  • OPAMERRLOGLEN — sets the number of log lines printed when a sub-process fails. 0 to print all of them.
  • OPAMEXTERNALSOLVER — see the option --solver.
  • OPAMFAKE — see the option --fake.
  • OPAMFETCH — specifies how to download files: either wget, curl or a custom command where the variables %{url}%, %{out}%, %{retry}%, %{compress}% and %{checksum}% will be replaced. overrides the 'download-command' value from the main config file.
  • OPAMFIXUPCRITERIA — same as OPAMUPGRADECRITERIA, but specific to fixup and reinstall.
  • OPAMIGNOREAVAILABLE — see the install option --ignore-available-on.
  • OPAMIGNORECONSTRAINTS — see the install option --ignore-constraints-on.
  • OPAMIGNOREPINDEPENDS — see the option --ignore-pin-depends.
  • OPAMINPLACEBUILD — see the option --inplace-build.
  • OPAMJOBS — sets the maximum number of parallel workers to run.
  • OPAMJSON — log json output to the given file (use the character % to index the files).
  • OPAMKEEPBUILDDIR — see the install option --keep-build-dir.
  • OPAMKEEPLOGS — tells opam to not remove some temporary command logs and some backups. this skips some finalisers and may also help you get more reliable backtraces.
  • OPAMLOCKED — the combination of the --locked and --lock-suffix options.
  • OPAMLOGS logdir — sets the log directory, default is a temporary directory in /tmp.
  • OPAMMAKECMD — set the system make command to use.
  • OPAMMERGEOUT — merge process outputs, stderr on stdout.
  • OPAMNO — answer no to any question asked, see the options --no and --confirm-level. OPAMNO is ignored if either OPAMCONFIRMLEVEL or OPAMYES is set.
  • OPAMNOAGGREGATE — with opam admin check, don't aggregate packages.
  • OPAMNOASPCUD — Deprecated. 🫠
  • OPAMNOAUTOUPGRADE — disables automatic internal upgrade of repositories in an earlier format to the current one, on update or init.
  • OPAMNOCHECKSUMS — enables the option --no-checksums when available.
  • OPAMNODEPEXTS — disables system dependencies handling, see the option --no-depexts.
  • OPAMNOENVNOTICE — Internal.
  • OPAMNOSELFUPGRADE — see the option --no-self-upgrade.
  • OPAMPINKINDAUTO — sets whether version control systems should be detected when pinning to a local path. enabled by default since 1.3.0.
  • OPAMPRECISETRACKING — fine grain tracking of directories.
  • OPAMPREPRO — set this to false to disable CUDF preprocessing. less efficient, but might help debugging a solver issue.
  • OPAMREPOSITORYTARRING — internally store all non-vcs repositories as tar.gz files (by default, http repositories are stored as archive). this can be much faster on filesystems that don't cope well with scanning large trees. all operations are done in-memory, no I/O for scanning the repository. 🧚
  • OPAMREQUIRECHECKSUMS — enables the option --require-checksums when available (e.g. for opam install).
  • OPAMRETRIES — sets the number of tries before failing downloads.
  • OPAMREUSEBUILDDIR — see the option --reuse-build-dir.
  • OPAMROOT — see the option --root. this is automatically set by opam env --root=DIR --set-root.
  • OPAMROOTISOK — don't complain when running as root.
  • OPAMSAFE — see the option --safe.
  • OPAMSHOW — see the option --show.
  • OPAMSKIPUPDATE — see the option --skip-updates.
  • OPAMSKIPVERSIONCHECKS — bypasses some version checks. Unsafe, for compatibility testing only. ⚠️ bestie be careful.
  • OPAMSOLVERALLOWSUBOPTIMAL — (default true) allows some solvers to still return a solution when they reach timeout; while the solution remains assured to be consistent, there is no guarantee in this case that it fits the expected optimisation criteria. if true, opam will continue with a warning, if false a timeout is an error. currently only the builtin-z3 backend handles this degraded case.
  • OPAMSOLVERTIMEOUT — change the time allowance of the solver. default is 60.0, set to 0 for unlimited. note that all solvers may not support this option.
  • OPAMSOLVERTOLERANCE — changes the tolerance towards the solver choosing an unoptimized solution (i.e. it might pull outdated packages 👀). typical values range from 0.0 (best solution known to the solver) to 1.0 (unoptimized solution). default is 0.0. this option is useful in case the solver can't find a solution in a reasonable time (see $OPAMSOLVERTIMEOUT). note that all solvers may not support this option.
  • OPAMSTATS — Removed in 2.4. 💀
  • OPAMSTATUSLINE — display a dynamic status line showing what's currently going on on the terminal (one of always, never or auto).
  • OPAMSTRICT — fail on inconsistencies (file reading, switch import, etc.).
  • OPAMSWITCH — see the option --switch. automatically set by opam env --switch=SWITCH --set-switch.
  • OPAMUNLOCKBASE — see the install option --unlock-base.
  • OPAMUPGRADECRITERIA — specifies user preferences for dependency solving when performing an upgrade. overrides OPAMCRITERIA in upgrades if both are set. see also the option --criteria.
  • OPAMUSEINTERNALSOLVER — see the option --use-internal-solver.
  • OPAMUSEOPENSSL — Removed in 2.2. 💀
  • OPAMUTF8 — use UTF8 characters in output (one of always, never or auto). by default auto, which is determined from the locale.
  • OPAMUTF8MSGS — use extended UTF8 characters (camels 🐫) in opam messages. implies OPAMUTF8. this is set by default on macOS only.
  • OPAMVALIDATIONHOOK — if set, uses the %{hook}% command to validate an opam repository update.
  • OPAMVERBOSE — see the option --verbose.
  • OPAMVERBOSEON — see the option --verbose-on.
  • OPAMVERSIONLAGPOWER — do not use. 🙅‍♀️ (for real. don't.)
  • OPAMWITHDEVSETUP — see the install option --with-dev-setup.
  • OPAMWITHDOC — see the install option --with-doc.
  • OPAMWITHTEST — see the install option --with-test.
  • OPAMWORKINGDIR — see the option --working-dir.
  • OPAMYES — see the options --yes and --confirm-level. OPAMYES has priority over OPAMNO and is ignored if OPAMCONFIRMLEVEL is set.
  • OPAMVAR_var — overrides the contents of the variable var when substituting %{var}% strings in opam files.
  • OPAMVAR_package_var — overrides the contents of the variable package:var when substituting %{package:var}% strings in opam files.

💅 CLI VERSION 💅

okay so this next bit is the part where past-you and future-you team up, and it's lowkey iconic. all scripts and programmatic invocations of opam should use --cli in order to ensure that they work seamlessly with future versions of the opam client. additionally, blog posts or other documentation can benefit, as it prevents information from becoming stale. 📚✨

although opam only supports roots (~/.opam/) for the current version, it does provide backwards compatibility for its command-line interface. slay.

since CLI version support was only added in opam 2.1, use OPAMCLI to select 2.0 support (as opam 2.0 will just ignore it), and --cli=2.1 for 2.1 (or later) versions, since an environment variable controlling the parsing of syntax is brittle. to this end, opam displays a warning if OPAMCLI specifies a valid version other than 2.0, and also if --cli=2.0 is specified. 🎀

the command-line version is selected by using the --cli option or the OPAMCLI environment variable. --cli may be specified more than once, where the last instance takes precedence. OPAMCLI is only inspected if --cli is not given. 👑

bestie reminder: if you're writing anything that talks to opam programmatically, pass --cli and thank yourself later. iykyk. 💖

💀 EXIT STATUS 💀

okay bestie, real talk — the exit code is the receipt of what just happened. every command hands one back, and here's the whole chart.

✨ ONE BIG EXCEPTION before we start, and it's important: the exec command is the rebel of the family. It returns 127 if the command wasn't found or couldn't be executed at all, and otherwise it just returns the command's own exit value. no vibes, no filtering, just passing it straight through. 💅
  • 0 — Success ✨ or, for boolean queries, true. she ate.
  • 1 — False. This one shows up when a boolean return value is expected, like when you run with --check, or for queries such as opam lint.
  • 2 — Bad command-line arguments 😭 or command-line arguments that point at an invalid context (say, a file that doesn't follow the expected format).
  • 5 — Not found. You asked for something — a package, a version, a repository, whatever — and it genuinely could not be found. 🫥
  • 10 — Aborted. The operation needed confirmation and you didn't give it. fair honestly.
  • 15 — Could not acquire the locks required for the operation. 🔒 someone else is in there.
  • 20 — There is no solution to the user request. This can happen when you ask to install two incompatible packages, for example.
  • 30 — Error in package definition, or other metadata files. Heads up: using --strict raises this error more often.
  • 31 — Package script error. Some package operations were unsuccessful. This may be an error in the packages or an incompatibility with your system. It can be a partial error.
  • 40 — Sync error. Could not fetch some remotes from the network. Also can be a partial error.
  • 50 — Configuration error. Opam or system configuration doesn't allow the operation, and it needs fixing.
  • 60 — Solver failure. The solver failed to return a sound answer. It can be due to a broken external solver, or an error in solver configuration. 🧠💥
  • 99 — Internal error. Something went wrong, most likely a bug in opam itself. not our fault, not yours either.
  • 130 — User interrupt. SIGINT was received — generally because the user pressed Ctrl+C. iconic behaviour, no notes.

and then there's this little cluster at the end, also on the list:

  • 0 — on success.
  • 123 — on indiscriminate errors reported on standard error.
  • 124 — on command line parsing errors.
  • 125 — on unexpected internal errors (bugs). 🐛

🌈 FURTHER DOCUMENTATION 🌈

See https://opam.ocaml.org/doc. that's the tea, go read it, iykyk 📚✨

👑 AUTHORS 👑

the whole friend group that made this happen, in order, with their emails, exactly as the page lists them:

  • David Allsopp <david@tarides.com>
  • Vincent Bernardoff <vb@luminar.eu.org>
  • Raja Boujbel <raja.boujbel@ocamlpro.com>
  • Kate Deplaix <kit-ty-kate@exn.st>
  • Roberto Di Cosmo <roberto@dicosmo.org>
  • Thomas Gazagnaire <thomas@gazagnaire.org>
  • Louis Gesbert <louis.gesbert@ocamlpro.com>
  • Fabrice Le Fessant <Fabrice.Le_fessant@inria.fr>
  • Anil Madhavapeddy <anil@recoil.org>
  • Guillem Rieu <guillem.rieu@ocamlpro.com>
  • Ralf Treinen <ralf.treinen@pps.jussieu.fr>
  • Frederic Tuong <tuong@users.gforge.inria.fr>

🦋 SEE ALSO 🦋

  • opam(1) — that's the main character, go read her too 💖

🙈 BUGS 🙈

found something cursed? Check bug reports at https://github.com/ocaml/opam/issues. we're not mad, we're just disappointed. (we're not even disappointed. we love you. file the issue. 🫶)

and that's a wrap bestie!! 🎀 this whole thing is from Opam 2.6.1, dated OPAM-SWITCH(1) — yes the manual page IDs itself as the switch page, we don't question the queen's choices. mwah 💋

📦 where this page comes from