1OPAM(1) Opam Manual OPAM(1)
2
6 opam - source-based package management
7
9 opam COMMAND ...
10
12 Opam is a package manager. It uses the powerful mancoosi tools to
13 handle dependencies, including support for version constraints,
14 optional dependencies, and conflict management. The default
15 configuration binds it to the official package repository for OCaml.
16 It has support for different remote repositories such as HTTP, rsync,
18 git, darcs and mercurial. Everything is installed within a local opam
19 directory, that can include multiple installation prefixes with
20 different sets of intalled packages.
21 Use either opam <command> --help or opam help <command> for more
23 information on a specific command.
24
26 admin
27 Tools for repository administrators
28 clean
30 Cleans up opam caches
31 config
33 Display configuration options for packages.
34 env Prints appropriate shell variable assignments to stdout
36 exec
38 Executes a command in the proper opam environment
39 help
41 Display help about opam and opam commands.
42 init
44 Initialize opam state, or set init options.
45 install
47 Install a list of packages.
48 lint
50 Checks and validate package description ('opam') files.
51 list
53 Display the list of available packages.
54 lock
56 Create locked opam files to share build environments across hosts.
57 option
59 Global and switch configuration options settings
60 pin Pin a given package to a specific version or source.
62 reinstall
64 Reinstall a list of packages.
65 remove
67 Remove a list of packages.
68 repository
70 Manage opam repositories.
71 show
73 Display information about specific packages.
74 source
76 Get the source of an opam package.
77 switch
79 Manage multiple installation prefixes.
80 update
82 Update the list of available packages.
83 upgrade
85 Upgrade the installed package to latest version.
86 var Display and update the value associated with a given variable
88
90 info
91 An alias for show.
92 remote
94 An alias for repository.
95 search
97 An alias for list --search.
98 uninstall
100 An alias for remove.
101 unpin
103 An alias for pin remove.
104
106 --no
107 Answer no to all opam yes/no questions without prompting. See also
108 --confirm-level. This is equivalent to setting $OPAMNO to "true".
109 -y, --yes
111 Answer yes to all opam yes/no questions without prompting. See also
112 --confirm-level. This is equivalent to setting $OPAMYES to "true".
113
115 These options are common to all commands.
116 --best-effort
118 Don't fail if all requested packages can't be installed: try to
119 install as many as possible. Note that not all external solvers may
120 support this option (recent versions of aspcud or mccs should).
121 This is equivalent to setting $OPAMBESTEFFORT environment variable.
122 --cli=MAJOR.MINOR (absent=2.1)
124 Use the command-line interface syntax and semantics of MAJOR.MINOR.
125 Intended for any persistent use of opam (scripts, blog posts,
126 etc.), any version of opam in the same MAJOR series will behave as
127 for the specified MINOR release. The flag was not available in opam
128 2.0, so to select the 2.0 CLI, set the OPAMCLI environment variable
129 to 2.0 instead of using this parameter.
130 --color=WHEN
132 Colorize the output. WHEN must be one of `always', `never' or
133 `auto'.
134 --confirm-level=LEVEL
136 Confirmation level, LEVEL must be one of `ask', `no', `yes' or
137 `unsafe-yes'. Can be specified more than once. If --yes or --no are
138 also given, the value of the last --confirm-level is taken into
139 account. This is equivalent to setting $OPAMCONFIRMLEVEL`.
140 --criteria=CRITERIA
142 Specify user preferences for dependency solving for this run.
143 Overrides both $OPAMCRITERIA and $OPAMUPGRADECRITERIA. For details
144 on the supported language, and the external solvers available, see
145 http://opam.ocaml.org/doc/External_solvers.html. A general guide to
146 using solver preferences can be found at
147 http://www.dicosmo.org/Articles/usercriteria.pdf.
148 --cudf=FILENAME
150 Debug option: Save the CUDF requests sent to the solver to
151 FILENAME-<n>.cudf.
152 --debug
154 Print debug message to stderr. This is equivalent to setting
155 $OPAMDEBUG to "true".
156 --debug-level=LEVEL
158 Like --debug, but allows specifying the debug level (--debug sets
159 it to 1). Equivalent to setting $OPAMDEBUG to a positive integer.
160 --git-version
162 Print the git version of opam, if set (i.e. you are using a
163 development version), and exit.
164 --help[=FMT] (default=auto)
166 Show this help in format FMT. The value FMT must be one of `auto',
167 `pager', `groff' or `plain'. With `auto', the format is `pager` or
168 `plain' whenever the TERM env var is `dumb' or undefined.
169 --ignore-pin-depends
171 Ignore extra pins required by packages that get pinned, either
172 manually through opam pin or through opam install DIR. This is
173 equivalent to setting IGNOREPINDEPENDS=true.
174 --json=FILENAME
176 Save the results of the opam run in a computer-readable file. If
177 the filename contains the character `%', it will be replaced by an
178 index that doesn't overwrite an existing file. Similar to setting
179 the $OPAMJSON variable.
180 --no-aspcud
182 Removed in 2.1.
183 --no-auto-upgrade
185 When configuring or updating a repository that is written for an
186 earlier opam version (1.2), opam internally converts it to the
187 current format. This disables this behaviour. Note that
188 repositories should define their format version in a 'repo' file at
189 their root, or they will be assumed to be in the older format. It
190 is, in any case, preferable to upgrade the repositories manually
191 using opam admin upgrade [--mirror URL] when possible.
192 --no-self-upgrade
194 Opam will replace itself with a newer binary found at OPAMROOT/opam
195 if present. This disables this behaviour.
196 -q, --quiet
198 Disables --verbose.
199 --root=ROOT
201 Use ROOT as the current root path. This is equivalent to setting
202 $OPAMROOT to ROOT.
203 --safe, --readonly
205 Make sure nothing will be automatically updated or rewritten.
206 Useful for calling from completion scripts, for example. Will fail
207 whenever such an operation is needed ; also avoids waiting for
208 locks, skips interactive questions and overrides the $OPAMDEBUG
209 variable. This is equivalent to set environment variable $OPAMSAFE.
210 --solver=CMD
212 Specify the CUDF solver to use for resolving package installation
213 problems. This is either a predefined solver (this version of opam
214 supports builtin-mccs+lp(), builtin-mccs+glpk,
215 builtin-dummy-z3-solver, builtin-dummy-0install-solver, aspcud,
216 mccs, aspcud-old, packup), or a custom command that should contain
217 the variables %{input}%, %{output}%, %{criteria}%, and optionally
218 %{timeout}%. This is equivalent to setting $OPAMEXTERNALSOLVER.
219 --strict
221 Fail whenever an error is found in a package definition or a
222 configuration file. The default is to continue silently if
223 possible.
224 --switch=SWITCH
226 Use SWITCH as the current compiler switch. This is equivalent to
227 setting $OPAMSWITCH to SWITCH.
228 --use-internal-solver
230 Disable any external solver, and use the built-in one (this
231 requires that opam has been compiled with a built-in solver). This
232 is equivalent to setting $OPAMNOASPCUD or $OPAMUSEINTERNALSOLVER.
233 -v, --verbose
235 Be more verbose. One -v shows all package commands, repeat to also
236 display commands called internally (e.g. tar, curl, patch etc.)
237 Repeating n times is equivalent to setting $OPAMVERBOSE to "n".
238 --version
240 Show version information.
241 -w, --working-dir
243 Whenever updating packages that are bound to a local,
244 version-controlled directory, update to the current working state
245 of their source instead of the last committed state, or the ref
246 they are pointing to. As source directory is copied as it is, if it
247 isn't clean it may result on a opam build failure.This only affects
248 packages explicitly listed on the command-line.It can also be set
249 with $OPAMWORKINGDIR.
250
252 Opam makes use of the environment variables listed here. Boolean
253 variables should be set to "0", "no", "false" or the empty string to
254 disable, "1", "yes" or "true" to enable.
255 OPAMALLPARENS surround all filters with parenthesis.
257 OPAMASSUMEDEPEXTS see option `--assume-depexts'.
259 OPAMAUTOREMOVE see remove option `--auto-remove'.
261 OPAMBESTEFFORT see option `--best-effort'.
263 OPAMBESTEFFORTPREFIXCRITERIA sets the string that must be prepended to
265 the criteria when the `--best-effort' option is set, and is expected to
266 maximise the `opam-query' property in the solution.
267 OPAMBUILDDOC Removed in 2.1.
269 OPAMBUILDTEST Removed in 2.1.
271 OPAMCLI see option `--cli'.
273 OPAMCOLOR when set to always or never, sets a default value for the
275 `--color' option.
276 OPAMCONFIRMLEVEL see option `--confirm-level`. OPAMCONFIRMLEVEL has
278 priority over OPAMYES and OPAMNO.
279 OPAMCRITERIA specifies user preferences for dependency solving. The
281 default value depends on the solver version, use `config report' to
282 know the current setting. See also option --criteria.
283 OPAMCUDFFILE save the cudf graph to file-actions-explicit.dot.
285 OPAMCUDFTRIM controls the filtering of unrelated packages during CUDF
287 preprocessing.
288 OPAMCURL can be used to select a given 'curl' program. See OPAMFETCH
290 for more options.
291 OPAMDEBUG see options `--debug' and `--debug-level'.
293 OPAMDEBUGSECTIONS if set, limits debug messages to the space-separated
295 list of sections. Sections can optionally have a specific debug level
296 (for example, CLIENT:2 or CLIENT CUDF:2), but otherwise use
297 `--debug-level'.
298 OPAMDIGDEPTH defines how aggressive the lookup for conflicts during
300 CUDF preprocessing is.
301 OPAMDOWNLOADJOBS sets the maximum number of simultaneous downloads.
303 OPAMDROPWORKINGDIR overrides packages previously updated with
305 --working-dir on update. Without this variable set, opam would keep
306 them unchanged unless explicitly named on the command-line.
307 OPAMDRYRUN see option `--dry-run'.
309 OPAMEDITOR sets the editor to use for opam file editing, overrides
311 $EDITOR and $VISUAL.
312 OPAMERRLOGLEN sets the number of log lines printed when a sub-process
314 fails. 0 to print all.
315 OPAMEXTERNALSOLVER see option `--solver'.
317 OPAMFAKE see option `--fake'.
319 OPAMFETCH specifies how to download files: either `wget', `curl' or a
321 custom command where variables %{url}%, %{out}%, %{retry}%,
322 %{compress}% and %{checksum}% will be replaced. Overrides the
323 'download-command' value from the main config file.
324 OPAMFIXUPCRITERIA same as OPAMUPGRADECRITERIA, but specific to fixup.
326 OPAMIGNORECONSTRAINTS see install option `--ignore-constraints-on'.
328 OPAMIGNOREPINDEPENDS see option `--ignore-pin-depends'.
330 OPAMINPLACEBUILD see option `--inplace-build'.
332 OPAMJOBS sets the maximum number of parallel workers to run.
334 OPAMJSON log json output to the given file (use character `%' to index
336 the files).
337 OPAMKEEPBUILDDIR see install option `--keep-build-dir'.
339 OPAMKEEPLOGS tells opam to not remove some temporary command logs and
341 some backups. This skips some finalisers and may also help to get more
342 reliable backtraces.
343 OPAMLOCKED combination of `--locked' and `--lock-suffix' options.
345 OPAMLOGS logdir sets log directory, default is a temporary directory in
347 /tmp
348 OPAMMAKECMD set the system make command to use.
350 OPAMMERGEOUT merge process outputs, stderr on stdout.
352 OPAMNO answer no to any question asked, see options `--no` and
354 `--confirm-level`. OPAMNO is ignored if either OPAMCONFIRMLEVEL or
355 OPAMYES is set.
356 OPAMNOAGGREGATE with `opam admin check', don't aggregate packages.
358 OPAMNOASPCUD Deprecated.
360 OPAMNOAUTOUPGRADE disables automatic internal upgrade of repositories
362 in an earlier format to the current one, on 'update' or 'init'.
363 OPAMNOCHECKSUMS enables option --no-checksums when available.
365 OPAMNODEPEXTS disables system dependencies handling, see option
367 `--no-depexts'.
368 OPAMNOENVNOTICE Internal.
370 OPAMNOSELFUPGRADE see option `--no-self-upgrade'
372 OPAMPINKINDAUTO sets whether version control systems should be detected
374 when pinning to a local path. Enabled by default since 1.3.0.
375 OPAMPRECISETRACKING fine grain tracking of directories.
377 OPAMPREPRO set this to false to disable CUDF preprocessing. Less
379 efficient, but might help debugging solver issue.
380 OPAMREQUIRECHECKSUMS Enables option `--require-checksums' when
382 available (e.g. for `opam install').
383 OPAMRETRIES sets the number of tries before failing downloads.
385 OPAMREUSEBUILDDIR see option `--reuse-build-dir'.
387 OPAMROOT see option `--root'. This is automatically set by `opam env
389 --root=DIR --set-root'.
390 OPAMROOTISOK don't complain when running as root.
392 OPAMSAFE see option `--safe'.
394 OPAMSHOW see option `--show'.
396 OPAMSKIPUPDATE see option `--skip-updates'.
398 OPAMSKIPVERSIONCHECKS bypasses some version checks. Unsafe, for
400 compatibility testing only.
401 OPAMSOLVERALLOWSUBOPTIMAL (default `true') allows some solvers to still
403 return a solution when they reach timeout; while the solution remains
404 assured to be consistent, there is no guarantee in this case that it
405 fits the expected optimisation criteria. If `true', opam willcontinue
406 with a warning, if `false' a timeout is an error. Currently only the
407 builtin-z3 backend handles this degraded case.
408 OPAMSOLVERTIMEOUT change the time allowance of the solver. Default is
410 60.0, set to 0 for unlimited. Note that all solvers may not support
411 this option.
412 OPAMSTATS display stats at the end of command.
414 OPAMSTATUSLINE display a dynamic status line showing what's currently
416 going on on the terminal. (one of one of `always', `never' or `auto')
417 OPAMSTRICT fail on inconsistencies (file reading, switch import, etc.).
419 OPAMSWITCH see option `--switch'. Automatically set by `opam env
421 --switch=SWITCH --set-switch'.
422 OPAMUNLOCKBASE see install option `--unlock-base'.
424 OPAMUPGRADECRITERIA specifies user preferences for dependency solving
426 when performing an upgrade. Overrides OPAMCRITERIA in upgrades if both
427 are set. See also option --criteria.
428 OPAMUSEINTERNALSOLVER see option `--use-internal-solver'.
430 OPAMUSEOPENSSL force openssl use for hash computing.
432 OPAMUTF8 use UTF8 characters in output (one of one of `always', `never'
434 or `auto'). By default `auto', which is determined from the locale).
435 OPAMUTF8MSGS use extended UTF8 characters (camels) in opam messages.
437 Implies OPAMUTF8. This is set by default on OSX only.
438 OPAMVALIDATIONHOOK if set, uses the `%{hook%}' command to validate an
440 opam repository update.
441 OPAMVERBOSE see option `--verbose'.
443 OPAMVERSIONLAGPOWER do not use.
445 OPAMWITHDOC see install option `--with-doc'.
447 OPAMWITHTEST see install option `--with-test.
449 OPAMWORKINGDIR see option `--working-dir'.
451 OPAMYES see options `--yes' and `--confirm-level`. OPAMYES has has
453 priority over OPAMNO and is ignored if OPAMCONFIRMLEVEL is set.
454 OPAMVAR_var overrides the contents of the variable var when
456 substituting `%{var}%` strings in `opam` files.
457 OPAMVAR_package_var overrides the contents of the variable package:var
459 when substituting `%{package:var}%` strings in `opam` files.
460
462 All scripts and programmatic invocations of opam should use `--cli' in
463 order to ensure that they work seamlessly with future versions of the
464 opam client. Additionally, blog posts or other documentation can
465 benefit, as it prevents information from becoming stale.
466 Although opam only supports roots (~/.opam/) for the current version,
468 it does provide backwards compatibility for its command-line interface.
469 Since CLI version support was only added in opam 2.1, use OPAMCLI to
471 select 2.0 support (as opam 2.0 will just ignore it), and `--cli=2.1'
472 for 2.1 (or later) versions, since an environment variable controlling
473 the parsing of syntax is brittle. To this end, opam displays a warning
474 if OPAMCLI specifies a valid version other than 2.0, and also if
475 `--cli=2.0' is specified.
476 The command-line version is selected by using the `--cli' option or the
478 OPAMCLI environment variable. `--cli' may be specified morethan once,
479 where the last instance takes precedence. OPAMCLI is only inspected if
480 `--cli' is not given.
481
483 As an exception to the following, the `exec' command returns 127 if the
484 command was not found or couldn't be executed, and the command's exit
485 value otherwise.
486 0 Success, or true for boolean queries.
488 1 False. Returned when a boolean return value is expected, e.g. when
490 running with --check, or for queries like opam lint.
491 2 Bad command-line arguments, or command-line arguments pointing to
493 an invalid context (e.g. file not following the expected format).
494 5 Not found. You requested something (package, version, repository,
496 etc.) that couldn't be found.
497 10 Aborted. The operation required confirmation, which wasn't given.
499 15 Could not acquire the locks required for the operation.
501 20 There is no solution to the user request. This can be caused by
503 asking to install two incompatible packages, for example.
504 30 Error in package definition, or other metadata files. Using
506 --strict raises this error more often.
507 31 Package script error. Some package operations were unsuccessful.
509 This may be an error in the packages or an incompatibility with
510 your system. This can be a partial error.
511 40 Sync error. Could not fetch some remotes from the network. This can
513 be a partial error.
514 50 Configuration error. Opam or system configuration doesn't allow
516 operation, and needs fixing.
517 60 Solver failure. The solver failed to return a sound answer. It can
519 be due to a broken external solver, or an error in solver
520 configuration.
521 99 Internal error. Something went wrong, likely due to a bug in opam
523 itself.
524 130 User interrupt. SIGINT was received, generally due to the user
526 pressing Ctrl-C.
527
529 See https://opam.ocaml.org/doc.
530
532 Vincent Bernardoff <vb@luminar.eu.org>
533 Raja Boujbel <raja.boujbel@ocamlpro.com>
534 Roberto Di Cosmo <roberto@dicosmo.org>
535 Thomas Gazagnaire <thomas@gazagnaire.org>
536 Louis Gesbert <louis.gesbert@ocamlpro.com>
537 Fabrice Le Fessant <Fabrice.Le_fessant@inria.fr>
538 Anil Madhavapeddy <anil@recoil.org>
539 Guillem Rieu <guillem.rieu@ocamlpro.com>
540 Ralf Treinen <ralf.treinen@pps.jussieu.fr>
541 Frederic Tuong <tuong@users.gforge.inria.fr>
542
544 Check bug reports at https://github.com/ocaml/opam/issues.
545Opam 2.1.1 OPAM(1)