OPAM-INIT(1)

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

💖 OPAM-INIT(1) — the opam-init page, but make it make sense 💖

okay bestie, welcome to the Opam Manual section for opam-init. This is the page that teaches you how to birth your opam state into existence. Sit down, grab a strawberry drink 🍓, we're doing this.

✨ NAME ✨

opam-init — Initialize opam state, or set init options.

🦋 SYNOPSIS 🦋

opam init [OPTION]… [NAME] [ADDRESS]

👑 DESCRIPTION 👑

Initialise the opam state, or update opam init options.

so basically, the init command initialises a local "opam root" — that's ~/.opam/ by default, unless you override it with --root or the OPAMROOT environment variable — and that root is where opam keeps all its data and packages. 💅 This is a necessary step for normal opam operation, no skipsies, no shortcuts. The initial software repositories get fetched, and an initial 'switch' can also be installed, depending on your configuration and options. Wanna tweak all that later? That's what opam switch and opam repository are for, bestie.

The initial repository and defaults can be set through a configuration file found at ~/.opamrc or /etc/opamrc.

Also!! This command lets you customise some aspects of opam's shell integration — when you run it initially (which skips the interactive dialog), but honestly also at any later time. Versatile icon. ✨

🎀 ARGUMENTS 🎀

  • ADDRESS — the address of the initial package repository, used when creating a new opam root.
  • NAME (absent=default) — the name of the initial repository, used when creating a new opam root.

💅 OPTIONS 💅

  • -a, --auto-setup — automatically do a full setup, including adding a line to your shell init files. set it and forget it energy fr fr.
  • --bare — initialise the opam state but don't setup any compiler switch yet. just the skeleton, no compiler yet 🦴
  • --bypass-checks — skip all the checks on required or recommended tools and just assume everything is fine. living dangerously, love that for you 🙈
  • -c PACKAGE, --compiler=PACKAGE — set which compiler to install (when creating an initial switch).
  • --config=FILE — use the given init config file. If you repeat this, the latest one has the highest priority (i.e. each field gets its value from wherever it was defined last). You're also allowed to specify a URL pointing to a config file instead. fancy. 🌈
  • --cygwin-extra-packages=CYGWIN_PACKAGES — Windows only (Experimental). Specify additional packages to install with --cygwin-internal-install.
  • --cygwin-internal-install — Windows only (Experimental). Let opam setup and manage an internal Cygwin install (this one is the recommended one 💖).
  • --cygwin-local-install — Windows only (Experimental). Use a preexistent Cygwin install.
  • --cygwin-location=DIR — Windows only (Experimental). Specify the Cygwin root location.
  • --disable-completion — disable shell completion in opam init scripts. no autocomplete for you 😭
  • --disable-sandboxing — use a default configuration with sandboxing disabled. Heads up: this may be overridden by opamrc if --no-opamrc is not specified or if --config is used. Use this at your own risk — without sandboxing it is possible for a broken package script to delete all your files. like, ALL of them. 💀
  • --disable-shell-hook — disable registration of a shell hook in opam init scripts.
  • --dot-profile=FILENAME — name of the configuration file to update instead of ~/.profile or ~/.zshrc based on shell detection.
  • --enable-completion — setup shell completion in opam init scripts, for supported shells. ✨
  • --enable-shell-hook — setup opam init scripts to register a shell hook that will automatically keep the shell environment up-to-date at every prompt. main character automation behavior 👑
  • --git-location=DIR — Windows only (Experimental). Specify the git binary directory. Make sure that it doesn't contain bash in the same directory.
  • -i, --interactive — run the setup interactively. This is the default for an initial run, or when no more specific options are specified.
  • -k KIND, --kind=KIND — specify the kind of repository to be used. One of http, local, git, darcs or hg.
  • -n, --no-setup — do not update the user shell configuration to setup opam. This also implies --disable-shell-hook, unless --interactive is given or specified otherwise.
  • --no-cygwin-setup — Experimental. Don't setup Cygwin.
  • --no-git-location — Experimental. Don't specify nor ask to specify the git binary directory.
  • --no-opamrc — don't read /etc/opamrc or ~/.opamrc: use the default settings and the files specified through --config only.
  • --reinit — re-run the initial checks and setup, according to opamrc, even if this is not a new opam root.
  • --shell=SHELL — sets the configuration mode for the opam environment appropriate for SHELL. One of bash, sh, csh, zsh, fish, pwsh, cmd or powershell. By default it's guessed from the parent processes and the $SHELL variable.
  • --shell-setup — automatically setup the user shell configuration for opam, e.g. adding a line to the ~/.profile file.
  • --show-default-opamrc — print the built-in default configuration to stdout and exit. peek behind the curtain energy 🧚

📝 CONFIGURATION FILE 📝

Any field from the built-in initial configuration can be overridden through ~/.opamrc, /etc/opamrc, or a file supplied with --config. And if you wanna see what the default configuration for this version of opam actually looks like, just grab it with --show-default-opamrc. 🫶

🔥 PACKAGE BUILD OPTIONS 🔥

  • --assume-depexts — skip the installation step for any missing system packages and attempt to proceed with compilation of the opam packages anyway. If the installation succeeds, opam won't prompt you again about these system packages. This is only meaningful if external dependency handling is enabled.
  • -b, --keep-build-dir — keep the build directories after compiling packages. This is equivalent to setting $OPAMKEEPBUILDDIR to "true".
  • --build-doc — Removed in 2.1, use --with-doc instead. she's gone, babe ✌️
  • --build-test — Removed in 2.1, use --with-test instead. also gone 😭
  • -d, --with-doc — build the package documentation. This only affects packages listed on the command-line. This is equivalent to setting $OPAMWITHDOC (or the deprecated $OPAMBUILDDOC) to "true".
  • --dry-run — simulate the command but don't actually perform any changes. This can also be set with the environment variable $OPAMDEBUG.
  • --fake — this option registers the actions into the opam database, without actually performing them. ⚠️ WARNING: This option is dangerous and likely to break your opam environment. You probably want --dry-run instead. You've been warned. 💀
  • --ignore-available-on[=PACKAGES] (default=) — forces opam to mark the listed packages as available. You can use this to test compatibility, but expect builds to break when you do. Note that version constraints of the packages' dependencies are unaffected.
  • --ignore-constraints-on[=PACKAGES] (default=) — forces opam to ignore version constraints on all dependencies to the listed packages. You can use this to test compatibility, but expect builds to break when you do. Note that availability of the packages, as well as version constraints on optional dependencies and conflicts, are unaffected. This is equivalent to setting $OPAMIGNORECONSTRAINTS.
  • --inplace-build — when compiling a package whose source is bound to a local directory, process the build and install actions directly in that directory, rather than in a clean copy handled by opam. This only affects packages explicitly listed on the command-line. This is equivalent to setting $OPAMINPLACEBUILD to "true".
  • -j JOBS, --jobs=JOBS — set the maximal number of concurrent jobs to use. The default value is calculated from the number of cores. You can also set it using the $OPAMJOBS environment variable.
  • --lock-suffix=SUFFIX (absent=locked) — set 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 is found (e.g. foo.opam.locked besides foo.opam), that one will be used instead. This is typically useful to offer a more specific set of dependencies and reproduce similar build contexts — hence the name, iykyk. The lock option can be used to generate such files, based on the versions of the dependencies currently installed on the host. This is equivalent to setting the $OPAMLOCKED environment variable. Note that this option doesn't generally affect already pinned packages.
  • -m MAKE, --make=MAKE — Removed in 2.1, use opam config set[-global] make MAKE instead. rip 🕊️
  • --no-checksums — do not verify the checksum of downloaded archives. This is equivalent to setting $OPAMNOCHECKSUMS to "true".
  • --no-depexts — temporarily disables handling of external dependencies. Use this if a package isn't available on your system package manager but you installed the required dependency by hand. Implies --assume-depexts, and stores the exceptions upon success as well.
  • --require-checksums — reject the installation of packages that don't provide a checksum for the upstream archives. This is equivalent to setting $OPAMREQUIRECHECKSUMS to "true".
  • --reuse-build-dir — reuse existing build directories (the ones kept by using --keep-build-dir) instead of compiling from a fresh clone of the source. This can be faster, but it can also lead to failures if the build systems of the packages don't handle upgrades of dependencies well. This is equivalent to setting $OPAMREUSEBUILDDIR to "true".
  • --show-actions — call the solver and display the actions. Don't perform any changes. This is equivalent to setting $OPAMSHOW.
  • --skip-updates — when running an install, upgrade or reinstall on source-pinned packages, they're normally updated from their origin first. This flag disables that behaviour and will keep them at their version in cache. This is equivalent to setting $OPAMSKIPUPDATE.
  • -t, --with-test — build and run the package unit-tests. This only affects packages listed on the command-line. This is equivalent to setting $OPAMWITHTEST (or the deprecated $OPAMBUILDTEST) to "true".
  • --unlock-base — Removed in 2.1, use --update-invariant instead. bye bestie 👋
  • --update-invariant — allow changes to the packages set as switch base (typically, the main compiler). Use with caution. This is equivalent to setting the $OPAMUNLOCKBASE environment variable.
  • --verbose-on=PACKAGES — be more verbose on specific packages. This is equivalent to setting $OPAMVERBOSE.
  • --with-dev-setup — include development tools only dependencies.

more parts coming bestie, don't go anywhere 🌸

✨ COMMON OPTIONS ✨

These ones are the universal besties — they work on literally every opam command. No cap. 💖

  • --best-effort — okay so if not every package you asked for can actually be installed, this stops opam from just ✨dying✨ about it. It'll try to install as many as it can instead. Small heads-up though: not all external solvers vibe with this option (recent versions of aspcud or mccs should be fine though 🫶). Same thing as setting the $OPAMBESTEFFORT environment variable.
  • --cli=MAJOR.MINOR (absent=2.6) — this one lets you use the command-line interface syntax and semantics of MAJOR.MINOR. It's made for when you're doing persistent stuff with opam (scripts, blog posts, that kind of thing) — any opam in the same MAJOR series will behave like the MINOR release you picked. 🎀 Heads up: this flag was not available in opam 2.0, so if you want the 2.0 CLI you gotta set the OPAMCLI environment variable to 2.0 instead of using this parameter. iykyk.
  • --color=WHEN — colorizes the output, obviously 💅 WHEN has to be one of always, never or auto.
  • --confirm-level=LEVEL — picks your confirmation level. LEVEL must be one of ask, no, yes or unsafe-yes. You can pass this bad boy more than once! And if you also give --yes or --no, whichever --confirm-level came last wins. Equivalent to setting $OPAMCONFIRMLEVEL.
  • --criteria=CRITERIA — sets your user preferences for dependency solving, just for this run. It overrides $OPAMCRITERIA, $OPAMFIXUPCRITERIA and $OPAMUPGRADECRITERIA. For the full tea on the supported language and what external solvers exist, go peep http://opam.ocaml.org/doc/External_solvers.html. And there's a general guide to using solver preferences at http://www.dicosmo.org/Articles/usercriteria.pdf 📚
  • --cudf=FILENAME — debug mode, bestie 🐛 saves the CUDF requests sent to the solver into FILENAME-<n>.cudf where <n> is the n-th call to the solver during the opam run.
  • --debug — prints debug messages to stderr. Same energy as setting $OPAMDEBUG to "true".
  • --debug-level=LEVEL — like --debug but you get to pick the debug level (--debug just sets it to 1). Equivalent to setting $OPAMDEBUG to a positive integer.
  • --git-version — prints the git version of opam if it's set (i.e. you're running a development version), then bounces. 👋
  • --help[=FMT] (default=auto) — shows this help in format FMT. FMT must be one of auto, pager, groff or plain. With auto, the format becomes pager or plain whenever the TERM env var is dumb or just... not there. 🙈
  • --ignore-pin-depends — ignores the extra pins that packages require when they get pinned, whether that's manually via opam pin or through opam install DIR. Equivalent to setting IGNOREPINDEPENDS=true.
  • --json=FILENAME — saves the results of the opam run into a computer-readable file 🖥️ if the filename has a % character in it, that character gets replaced by an index that won't overwrite an existing file. Similar to setting the $OPAMJSON variable.
  • --no — answers no to every single opam yes/no question, no prompting. See also --confirm-level. Equivalent to setting $OPAMNO to "true".
  • --no-aspcud — removed in 2.1 💀 it's gone, bestie.
  • --no-auto-upgrade — when opam configures or updates a repository written for an earlier opam version (1.2), it internally converts it to the current format. This flag turns that behaviour off. Note that repositories should define their format version in a 'repo' file at their root, or they'll be assumed to be in the older format. Honestly though, it's preferable in any case to upgrade the repositories manually using opam admin upgrade [--mirror URL] when you can. ✨
  • --no-self-upgrade — opam will replace itself with a newer binary found at OPAMROOT/opam if one's there. This disables that glow-up behaviour. 🦋
  • -q, --quiet — disables --verbose.
  • --root=ROOT — uses ROOT as the current root path. Equivalent to setting $OPAMROOT to ROOT.
  • --safe, --readonly — makes sure nothing gets automatically updated or rewritten. Super useful for calling from completion scripts and stuff like that. It'll fail whenever such an operation is needed; it also skips waiting for locks, skips interactive questions, and overrides the $OPAMDEBUG variable. Equivalent to setting the $OPAMSAFE environment variable. 🔒
  • --solver=CMD — picks the CUDF solver used 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}%. Equivalent to setting $OPAMEXTERNALSOLVER.
  • --strict — fails whenever an error shows up in a package definition or a configuration file. The default is to just silently carry on if possible. 😌
  • --switch=SWITCH — uses SWITCH as the current compiler switch. Equivalent to setting $OPAMSWITCH to SWITCH.
  • --use-internal-solver — disables any external solver and uses the built-in one instead (this needs opam to have been compiled with a built-in solver). Equivalent to setting $OPAMNOASPCUD or $OPAMUSEINTERNALSOLVER.
  • -v, --verbose — be more verbose ✨ one -v shows all package commands; repeat it to also display commands called internally (e.g. tar, curl, patch etc.). Repeating it n times is equivalent to setting $OPAMVERBOSE to "n".
  • --version — shows version information. simple as that bestie 🎀
  • -w, --working-dir — whenever you're updating packages bound to a local, version-controlled directory, this updates to the current working state of their source instead of the last committed state, or the ref they're pointing to. ⚠️ Careful though — since the source directory is copied as it is, if it isn't clean it may result in a opam build failure. This only affects packages explicitly listed on the command-line. Can also be set with $OPAMWORKINGDIR.
  • -y, --yes — answers yes to all opam yes/no questions without prompting. See also --confirm-level. Equivalent to setting $OPAMYES to "true".

🦋 ENVIRONMENT 🦋

Okay so opam is obsessed with environment variables, bestie. Here's the whole roster. If a variable is a boolean, set it to "0", "no", "false" or literally the empty string to turn it off, and "1", "yes" or "true" to turn it on. That's the vibe check for booleans. ✨

  • OPAMALLPARENS — surrounds all filters with parentheses. All of them. Every single one.
  • OPAMASSUMEDEPEXTS — peek at the --assume-depexts option, it's giving the same energy.
  • OPAMAUTOANSWER — internal use only, bestie, nothing for you here 🙈
  • OPAMAUTOREMOVE — see the remove option --auto-remove.
  • OPAMBESTEFFORT — see option --best-effort.
  • OPAMBESTEFFORTPREFIXCRITERIA — sets the string that must be prepended to the criteria when the --best-effort option is set, and it's expected to maximise the opam-query property in the solution. Very specific, very iconic.
  • OPAMBUILDDOC — Removed in 2.1. 💀 gone girl
  • OPAMBUILDTEST — Removed in 2.1. also 💀
  • OPAMCLI — see option --cli.
  • OPAMCOLOR — when set to always or never, sets a default value for the --color option.
  • OPAMCONFIRMLEVEL — see option --confirm-level. Heads up: OPAMCONFIRMLEVEL has priority over OPAMYES and OPAMNO. It's the main character here, no cap.
  • OPAMCRITERIA — specifies user preferences for dependency solving. The default value depends on the solver version, so run config report to know the current setting. See also 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 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. Dig, queen 🕳️
  • 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 explicitly named on the command-line.
  • OPAMDRYRUN — see option --dry-run.
  • OPAMEDITOR — sets the editor to use for opam file editing, and it overrides $EDITOR and $VISUAL. It said "I'm the editor now" 💅
  • OPAMERRLOGLEN — sets the number of log lines printed when a sub-process fails. 0 to print all.
  • OPAMEXTERNALSOLVER — see option --solver.
  • OPAMFAKE — see option --fake.
  • OPAMFETCH — specifies how to download files: either wget, curl or a custom command where 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 install option --ignore-available-on.
  • OPAMIGNORECONSTRAINTS — see install option --ignore-constraints-on.
  • OPAMIGNOREPINDEPENDS — see option --ignore-pin-depends.
  • OPAMINPLACEBUILD — see option --inplace-build.
  • OPAMJOBS — sets the maximum number of parallel workers to run.
  • OPAMJSON — log json output to the given file (use character % to index the files).
  • OPAMKEEPBUILDDIR — see 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 to get more reliable backtraces.
  • OPAMLOCKED — combination of --locked and --lock-suffix options.
  • OPAMLOGS — logdir sets 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 options --no and --confirm-level. But ngl: 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 option --no-checksums when available.
  • OPAMNODEPEXTS — disables system dependencies handling, see option --no-depexts.
  • OPAMNOENVNOTICE — Internal.
  • OPAMNOSELFUPGRADE — see 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 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 operation are done in-memory, no I/O for scanning the repository.
  • OPAMREQUIRECHECKSUMS — Enables option --require-checksums when available (e.g. for opam install).
  • OPAMRETRIES — sets the number of tries before failing downloads.
  • OPAMREUSEBUILDDIR — see option --reuse-build-dir.
  • OPAMROOT — see option --root. This is automatically set by opam env --root=DIR --set-root.
  • OPAMROOTISOK — don't complain when running as root. (root? as root?? okay pioneeer 🫶)
  • OPAMSAFE — see option --safe.
  • OPAMSHOW — see option --show.
  • OPAMSKIPUPDATE — see option --skip-updates.
  • OPAMSKIPVERSIONCHECKS — bypasses some version checks. Unsafe, for compatibility testing only. Do not make this your whole personality.
  • 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. 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 option --switch. Automatically set by opam env --switch=SWITCH --set-switch.
  • OPAMUNLOCKBASE — see 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 option --criteria.
  • OPAMUSEINTERNALSOLVER — see 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. 🐪 camels!!
  • OPAMVALIDATIONHOOK — if set, uses the %{hook}% command to validate an opam repository update.
  • OPAMVERBOSE — see option --verbose.
  • OPAMVERBOSEON — see option --verbose-on
  • OPAMVERSIONLAGPOWER — do not use. that's it. that's the whole description. do NOT use it bestie 🙅‍♀️
  • OPAMWITHDEVSETUP — see install option --with-dev-setup.
  • OPAMWITHDOC — see install option --with-doc.
  • OPAMWITHTEST — see install option `--with-test.
  • OPAMWORKINGDIR — see option --working-dir.
  • OPAMYES — see 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, all scripts and programmatic invocations of opam should use --cli, because that's how you make sure they work seamlessly with future versions of the opam client. And honestly? Blog posts and other documentation benefit too, because it stops information from becoming stale. Slay.

Although opam only supports roots (~/.opam/) for the current version, it does provide backwards compatibility for its command-line interface. So you're covered, bestie. 💖

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. Yeah. It will call you out. 🔥

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. Last one wins, always. Periodt. 💅

--cli
OPAMCLI
--cli=2.0
--cli=2.1

💀 EXIT STATUS 💀

okay bestie, this is the part where opam tells you what it's feeling by yeeting a number at your shell. every exit code is a whole mood, and they're all here, no cap. 🫶

✨ one (1) exception before we start, and she's iconic: the exec command does not play by these rules. exec returns 127 if the command wasn't found or couldn't be executed, and otherwise it returns the command's own exit value. that's it, that's the exception, moving on. 💅
  • 0 — Success 🎉 or, for boolean queries, true.
  • 1 — False. comes back at you when a boolean return value is expected, like when you're running with --check, or for queries like opam lint.
  • 2 — Bad command-line arguments 😭 or command-line arguments that point at an invalid context (e.g. a file that isn't in the expected format).
  • 5 — Not found. you asked for something (package, version, repository, etc.) and it simply wasn't there. 🕳️
  • 10 — Aborted. the operation needed confirmation and you didn't give it. 🙈
  • 15 — Could not acquire the locks required for the operation. 🔒
  • 20 — There's no solution to the user request. this can happen when you ask to install two incompatible packages, for example. bestie. you can't have both. 😭
  • 30 — Error in package definition, or other metadata files. 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. this can be a partial error.
  • 40 — Sync error. couldn't fetch some remotes from the network. this can be a partial error too.
  • 50 — Configuration error. opam or your 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, and it's likely a bug in opam itself. 💀
  • 130 — User interrupt. SIGINT was received, generally because the user pressed Ctrl+C.

and then there's this second little batch of generic ones, all lowercase and businesslike, slay:

  • 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 link, go read, it's giving study session. 🧚

👑 AUTHORS 👑

the whole squad, and honestly? legends. every single one. 💖

  • 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) — yeah. the main character. go say hi. ✨

🐛 BUGS 🐛

found something cursed? check bug reports at https://github.com/ocaml/opam/issues. tell them everything, they're nice about it, i promise. 🫶

okay bestie that's the whole page!! you just read the entire manual like the absolute icon you are. 👑 this was Opam 2.6.1, page OPAM-INIT(1), and you've officially graduated. go init something. i'm obsessed. 💖✨🎀🦋

📦 where this page comes from