1OPAM(1)                           Opam Manual                          OPAM(1)
2
3
4

NAME

6       opam - source-based package management
7

SYNOPSIS

9       opam [COMMAND] …
10

DESCRIPTION

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
17       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
22       Use either opam <command> --help or opam help <command> for more
23       information on a specific command.
24

COMMANDS

26       admin [OPTION]…
27           Tools for repository administrators
28
29       clean [OPTION]…
30           Cleans up opam caches
31
32       config [OPTION]… [COMMAND] [ARG]…
33           Display configuration options for packages.
34
35       env [OPTION]…
36           Prints appropriate shell variable assignments to stdout
37
38       exec [OPTION]… COMMAND [ARG]...
39           Executes a command in the proper opam environment
40
41       help [--man-format=FMT] [OPTION]… [TOPIC]
42           Display help about opam and opam commands.
43
44       init [OPTION]… [NAME] [ADDRESS]
45           Initialize opam state, or set init options.
46
47       install [OPTION]… [PACKAGES]…
48           Install a list of packages.
49
50       lint [OPTION]… [FILES]…
51           Checks and validate package description ('opam') files.
52
53       list [OPTION]… [PATTERNS]…
54           Display the list of available packages.
55
56       lock [OPTION]… [PACKAGES]…
57           Create locked opam files to share build environments across hosts.
58
59       option [--global] [--no] [--yes] [OPTION]… [FIELD[(=|+=|-=)[VALUE]]]
60           Global and switch configuration options settings
61
62       pin [OPTION]… [COMMAND] [ARG]…
63           Pin a given package to a specific version or source.
64
65       reinstall [OPTION]… [PACKAGES]…
66           Reinstall a list of packages.
67
68       remove [OPTION]… [PACKAGES]…
69           Remove a list of packages.
70
71       repository [OPTION]… [COMMAND] [ARG]…
72           Manage opam repositories.
73
74       show [OPTION]… [PACKAGES]…
75           Display information about specific packages.
76
77       source [OPTION]… PACKAGE
78           Get the source of an opam package.
79
80       switch [OPTION]… [COMMAND] [ARG]…
81           Manage multiple installation prefixes.
82
83       update [OPTION]… [NAMES]…
84           Update the list of available packages.
85
86       upgrade [OPTION]… [PACKAGES]…
87           Upgrade the installed package to latest version.
88
89       var [OPTION]… [VAR[=[VALUE]]]
90           Display and update the value associated with a given variable
91

COMMAND ALIASES

93       info [OPTION]… [PACKAGES]…
94           An alias for show.
95
96       remote [OPTION]… [COMMAND] [ARG]…
97           An alias for repository.
98
99       search [OPTION]… [PATTERNS]…
100           An alias for list --search.
101
102       uninstall [OPTION]… [PACKAGES]…
103           An alias for remove.
104
105       unpin [OPTION]… [ARG]…
106           An alias for pin remove.
107

OPTIONS

109       --no
110           Answer no to all opam yes/no questions without prompting. See also
111           --confirm-level. This is equivalent to setting $OPAMNO to "true".
112
113       -y, --yes
114           Answer yes to all opam yes/no questions without prompting. See also
115           --confirm-level. This is equivalent to setting $OPAMYES to "true".
116

COMMON OPTIONS

118       These options are common to all commands.
119
120       --best-effort
121           Don't fail if all requested packages can't be installed: try to
122           install as many as possible. Note that not all external solvers may
123           support this option (recent versions of aspcud or mccs should).
124           This is equivalent to setting $OPAMBESTEFFORT environment variable.
125
126       --cli=MAJOR.MINOR (absent=2.1)
127           Use the command-line interface syntax and semantics of MAJOR.MINOR.
128           Intended for any persistent use of opam (scripts, blog posts,
129           etc.), any version of opam in the same MAJOR series will behave as
130           for the specified MINOR release. The flag was not available in opam
131           2.0, so to select the 2.0 CLI, set the OPAMCLI environment variable
132           to 2.0 instead of using this parameter.
133
134       --color=WHEN
135           Colorize the output. WHEN must be one of always, never or auto.
136
137       --confirm-level=LEVEL
138           Confirmation level, LEVEL must be one of ask, no, yes or
139           unsafe-yes. Can be specified more than once. If --yes or --no are
140           also given, the value of the last --confirm-level is taken into
141           account. This is equivalent to setting  $OPAMCONFIRMLEVEL`.
142
143       --criteria=CRITERIA
144           Specify user preferences for dependency solving for this run.
145           Overrides both $OPAMCRITERIA and $OPAMUPGRADECRITERIA. For details
146           on the supported language, and the external solvers available, see
147           http://opam.ocaml.org/doc/External_solvers.html. A general guide to
148           using solver preferences can be found at
149           http://www.dicosmo.org/Articles/usercriteria.pdf.
150
151       --cudf=FILENAME
152           Debug option: Save the CUDF requests sent to the solver to
153           FILENAME-<n>.cudf.
154
155       --debug
156           Print debug message to stderr. This is equivalent to setting
157           $OPAMDEBUG to "true".
158
159       --debug-level=LEVEL
160           Like --debug, but allows specifying the debug level (--debug sets
161           it to 1). Equivalent to setting $OPAMDEBUG to a positive integer.
162
163       --git-version
164           Print the git version of opam, if set (i.e. you are using a
165           development version), and exit.
166
167       --help[=FMT] (default=auto)
168           Show this help in format FMT. The value FMT must be one of auto,
169           pager, groff or plain. With auto, the format is pager or plain
170           whenever the TERM env var is dumb or undefined.
171
172       --ignore-pin-depends
173           Ignore extra pins required by packages that get pinned, either
174           manually through opam pin or through opam install DIR. This is
175           equivalent to setting IGNOREPINDEPENDS=true.
176
177       --json=FILENAME
178           Save the results of the opam run in a computer-readable file. If
179           the filename contains the character `%', it will be replaced by an
180           index that doesn't overwrite an existing file. Similar to setting
181           the $OPAMJSON variable.
182
183       --no-aspcud
184           Removed in 2.1.
185
186       --no-auto-upgrade
187           When configuring or updating a repository that is written for an
188           earlier opam version (1.2), opam internally converts it to the
189           current format. This disables this behaviour. Note that
190           repositories should define their format version in a 'repo' file at
191           their root, or they will be assumed to be in the older format. It
192           is, in any case, preferable to upgrade the repositories manually
193           using opam admin upgrade [--mirror URL] when possible.
194
195       --no-self-upgrade
196           Opam will replace itself with a newer binary found at OPAMROOT/opam
197           if present. This disables this behaviour.
198
199       -q, --quiet
200           Disables --verbose.
201
202       --root=ROOT
203           Use ROOT as the current root path. This is equivalent to setting
204           $OPAMROOT to ROOT.
205
206       --safe, --readonly
207           Make sure nothing will be automatically updated or rewritten.
208           Useful for calling from completion scripts, for example. Will fail
209           whenever such an operation is needed ; also avoids waiting for
210           locks, skips interactive questions and overrides the $OPAMDEBUG
211           variable. This is equivalent to set environment variable $OPAMSAFE.
212
213       --solver=CMD
214           Specify the CUDF solver to use for resolving package installation
215           problems. This is either a predefined solver (this version of opam
216           supports builtin-mccs+lp(), builtin-mccs+glpk,
217           builtin-dummy-z3-solver, builtin-dummy-0install-solver, aspcud,
218           mccs, aspcud-old, packup), or a custom command that should contain
219           the variables %{input}%, %{output}%, %{criteria}%, and optionally
220           %{timeout}%. This is equivalent to setting $OPAMEXTERNALSOLVER.
221
222       --strict
223           Fail whenever an error is found in a package definition or a
224           configuration file. The default is to continue silently if
225           possible.
226
227       --switch=SWITCH
228           Use SWITCH as the current compiler switch. This is equivalent to
229           setting $OPAMSWITCH to SWITCH.
230
231       --use-internal-solver
232           Disable any external solver, and use the built-in one (this
233           requires that opam has been compiled with a built-in solver). This
234           is equivalent to setting $OPAMNOASPCUD or $OPAMUSEINTERNALSOLVER.
235
236       -v, --verbose
237           Be more verbose. One -v shows all package commands, repeat to also
238           display commands called internally (e.g. tar, curl, patch etc.)
239           Repeating n times is equivalent to setting $OPAMVERBOSE to "n".
240
241       --version
242           Show version information.
243
244       -w, --working-dir
245           Whenever updating packages that are bound to a local,
246           version-controlled directory, update to the current working state
247           of their source instead of the last committed state, or the ref
248           they are pointing to. As source directory is copied as it is, if it
249           isn't clean it may result on a opam build failure.This only affects
250           packages explicitly listed on the command-line.It can also be set
251           with $OPAMWORKINGDIR.
252

ENVIRONMENT

254       Opam makes use of the environment variables listed here. Boolean
255       variables should be set to "0", "no", "false" or the empty string to
256       disable, "1", "yes" or "true" to enable.
257
258       OPAMALLPARENS surround all filters with parenthesis.
259
260       OPAMASSUMEDEPEXTS see option `--assume-depexts'.
261
262       OPAMAUTOREMOVE see remove option `--auto-remove'.
263
264       OPAMBESTEFFORT see option `--best-effort'.
265
266       OPAMBESTEFFORTPREFIXCRITERIA sets the string that must be prepended to
267       the criteria when the `--best-effort' option is set, and is expected to
268       maximise the `opam-query' property in the solution.
269
270       OPAMBUILDDOC Removed in 2.1.
271
272       OPAMBUILDTEST Removed in 2.1.
273
274       OPAMCLI see option `--cli'.
275
276       OPAMCOLOR when set to always or never, sets a default value for the
277       `--color' option.
278
279       OPAMCONFIRMLEVEL see option `--confirm-level`. OPAMCONFIRMLEVEL has
280       priority over OPAMYES and OPAMNO.
281
282       OPAMCRITERIA specifies user preferences for dependency solving. The
283       default value depends on the solver version, use `config report' to
284       know the current setting. See also option --criteria.
285
286       OPAMCUDFFILE save the cudf graph to file-actions-explicit.dot.
287
288       OPAMCUDFTRIM controls the filtering of unrelated packages during CUDF
289       preprocessing.
290
291       OPAMCURL can be used to select a given 'curl' program. See OPAMFETCH
292       for more options.
293
294       OPAMDEBUG see options `--debug' and `--debug-level'.
295
296       OPAMDEBUGSECTIONS if set, limits debug messages to the space-separated
297       list of sections. Sections can optionally have a specific debug level
298       (for example, CLIENT:2 or CLIENT CUDF:2), but otherwise use
299       `--debug-level'.
300
301       OPAMDIGDEPTH defines how aggressive the lookup for conflicts during
302       CUDF preprocessing is.
303
304       OPAMDOWNLOADJOBS sets the maximum number of simultaneous downloads.
305
306       OPAMDROPWORKINGDIR overrides packages previously updated with
307       --working-dir on update. Without this variable set, opam would keep
308       them unchanged unless explicitly named on the command-line.
309
310       OPAMDRYRUN see option `--dry-run'.
311
312       OPAMEDITOR sets the editor to use for opam file editing, overrides
313       $EDITOR and $VISUAL.
314
315       OPAMERRLOGLEN sets the number of log lines printed when a sub-process
316       fails. 0 to print all.
317
318       OPAMEXTERNALSOLVER see option `--solver'.
319
320       OPAMFAKE see option `--fake'.
321
322       OPAMFETCH specifies how to download files: either `wget', `curl' or a
323       custom command where variables %{url}%, %{out}%, %{retry}%,
324       %{compress}% and %{checksum}% will be replaced. Overrides the
325       'download-command' value from the main config file.
326
327       OPAMFIXUPCRITERIA same as OPAMUPGRADECRITERIA, but specific to fixup.
328
329       OPAMIGNORECONSTRAINTS see install option `--ignore-constraints-on'.
330
331       OPAMIGNOREPINDEPENDS see option `--ignore-pin-depends'.
332
333       OPAMINPLACEBUILD see option `--inplace-build'.
334
335       OPAMJOBS sets the maximum number of parallel workers to run.
336
337       OPAMJSON log json output to the given file (use character `%' to index
338       the files).
339
340       OPAMKEEPBUILDDIR see install option `--keep-build-dir'.
341
342       OPAMKEEPLOGS tells opam to not remove some temporary command logs and
343       some backups. This skips some finalisers and may also help to get more
344       reliable backtraces.
345
346       OPAMLOCKED combination of `--locked' and `--lock-suffix' options.
347
348       OPAMLOGS logdir sets log directory, default is a temporary directory in
349       /tmp
350
351       OPAMMAKECMD set the system make command to use.
352
353       OPAMMERGEOUT merge process outputs, stderr on stdout.
354
355       OPAMNO answer no to any question asked, see options `--no` and
356       `--confirm-level`. OPAMNO is ignored if either OPAMCONFIRMLEVEL or
357       OPAMYES is set.
358
359       OPAMNOAGGREGATE with `opam admin check', don't aggregate packages.
360
361       OPAMNOASPCUD Deprecated.
362
363       OPAMNOAUTOUPGRADE disables automatic internal upgrade of repositories
364       in an earlier format to the current one, on 'update' or 'init'.
365
366       OPAMNOCHECKSUMS enables option --no-checksums when available.
367
368       OPAMNODEPEXTS disables system dependencies handling, see option
369       `--no-depexts'.
370
371       OPAMNOENVNOTICE Internal.
372
373       OPAMNOSELFUPGRADE see option `--no-self-upgrade'
374
375       OPAMPINKINDAUTO sets whether version control systems should be detected
376       when pinning to a local path. Enabled by default since 1.3.0.
377
378       OPAMPRECISETRACKING fine grain tracking of directories.
379
380       OPAMPREPRO set this to false to disable CUDF preprocessing. Less
381       efficient, but might help debugging solver issue.
382
383       OPAMREQUIRECHECKSUMS Enables option `--require-checksums' when
384       available (e.g. for `opam install').
385
386       OPAMRETRIES sets the number of tries before failing downloads.
387
388       OPAMREUSEBUILDDIR see option `--reuse-build-dir'.
389
390       OPAMROOT see option `--root'. This is automatically set by `opam env
391       --root=DIR --set-root'.
392
393       OPAMROOTISOK don't complain when running as root.
394
395       OPAMSAFE see option `--safe'.
396
397       OPAMSHOW see option `--show'.
398
399       OPAMSKIPUPDATE see option `--skip-updates'.
400
401       OPAMSKIPVERSIONCHECKS bypasses some version checks. Unsafe, for
402       compatibility testing only.
403
404       OPAMSOLVERALLOWSUBOPTIMAL (default `true') allows some solvers to still
405       return a solution when they reach timeout; while the solution remains
406       assured to be consistent, there is no guarantee in this case that it
407       fits the expected optimisation criteria. If `true', opam willcontinue
408       with a warning, if `false' a timeout is an error. Currently only the
409       builtin-z3 backend handles this degraded case.
410
411       OPAMSOLVERTIMEOUT change the time allowance of the solver. Default is
412       60.0, set to 0 for unlimited. Note that all solvers may not support
413       this option.
414
415       OPAMSTATS display stats at the end of command.
416
417       OPAMSTATUSLINE display a dynamic status line showing what's currently
418       going on on the terminal. (one of one of always, never or auto)
419
420       OPAMSTRICT fail on inconsistencies (file reading, switch import, etc.).
421
422       OPAMSWITCH see option `--switch'. Automatically set by `opam env
423       --switch=SWITCH --set-switch'.
424
425       OPAMUNLOCKBASE see install option `--unlock-base'.
426
427       OPAMUPGRADECRITERIA specifies user preferences for dependency solving
428       when performing an upgrade. Overrides OPAMCRITERIA in upgrades if both
429       are set. See also option --criteria.
430
431       OPAMUSEINTERNALSOLVER see option `--use-internal-solver'.
432
433       OPAMUSEOPENSSL force openssl use for hash computing.
434
435       OPAMUTF8 use UTF8 characters in output (one of one of always, never or
436       auto). By default `auto', which is determined from the locale).
437
438       OPAMUTF8MSGS use extended UTF8 characters (camels) in opam messages.
439       Implies OPAMUTF8. This is set by default on OSX only.
440
441       OPAMVALIDATIONHOOK if set, uses the `%{hook%}' command to validate an
442       opam repository update.
443
444       OPAMVERBOSE see option `--verbose'.
445
446       OPAMVERSIONLAGPOWER do not use.
447
448       OPAMWITHDOC see install option `--with-doc'.
449
450       OPAMWITHTEST see install option `--with-test.
451
452       OPAMWORKINGDIR see option `--working-dir'.
453
454       OPAMYES see options `--yes' and `--confirm-level`. OPAMYES has has
455       priority over OPAMNO and is ignored if OPAMCONFIRMLEVEL is set.
456
457       OPAMVAR_var overrides the contents of the variable var when
458       substituting `%{var}%` strings in `opam` files.
459
460       OPAMVAR_package_var overrides the contents of the variable package:var
461       when substituting `%{package:var}%` strings in `opam` files.
462

CLI VERSION

464       All scripts and programmatic invocations of opam should use `--cli' in
465       order to ensure that they work seamlessly with future versions of the
466       opam client. Additionally, blog posts or other documentation can
467       benefit, as it prevents information from becoming stale.
468
469       Although opam only supports roots (~/.opam/) for the current version,
470       it does provide backwards compatibility for its command-line interface.
471
472       Since CLI version support was only added in opam 2.1, use OPAMCLI to
473       select 2.0 support (as opam 2.0 will just ignore it), and `--cli=2.1'
474       for 2.1 (or later) versions, since an environment variable controlling
475       the parsing of syntax is brittle. To this end, opam displays a warning
476       if OPAMCLI specifies a valid version other than 2.0, and also if
477       `--cli=2.0' is specified.
478
479       The command-line version is selected by using the `--cli' option or the
480       OPAMCLI environment variable. `--cli' may be specified morethan once,
481       where the last instance takes precedence. OPAMCLI is only inspected if
482       `--cli' is not given.
483

EXIT STATUS

485       As an exception to the following, the `exec' command returns 127 if the
486       command was not found or couldn't be executed, and the command's exit
487       value otherwise.
488
489       0   Success, or true for boolean queries.
490
491       1   False. Returned when a boolean return value is expected, e.g. when
492           running with --check, or for queries like opam lint.
493
494       2   Bad command-line arguments, or command-line arguments pointing to
495           an invalid context (e.g. file not following the expected format).
496
497       5   Not found. You requested something (package, version, repository,
498           etc.) that couldn't be found.
499
500       10  Aborted. The operation required confirmation, which wasn't given.
501
502       15  Could not acquire the locks required for the operation.
503
504       20  There is no solution to the user request. This can be caused by
505           asking to install two incompatible packages, for example.
506
507       30  Error in package definition, or other metadata files. Using
508           --strict raises this error more often.
509
510       31  Package script error. Some package operations were unsuccessful.
511           This may be an error in the packages or an incompatibility with
512           your system. This can be a partial error.
513
514       40  Sync error. Could not fetch some remotes from the network. This can
515           be a partial error.
516
517       50  Configuration error. Opam or system configuration doesn't allow
518           operation, and needs fixing.
519
520       60  Solver failure. The solver failed to return a sound answer. It can
521           be due to a broken external solver, or an error in solver
522           configuration.
523
524       99  Internal error. Something went wrong, likely due to a bug in opam
525           itself.
526
527       130 User interrupt. SIGINT was received, generally due to the user
528           pressing Ctrl-C.
529

FURTHER DOCUMENTATION

531       See https://opam.ocaml.org/doc.
532

AUTHORS

534       Vincent Bernardoff <vb@luminar.eu.org>
535       Raja Boujbel <raja.boujbel@ocamlpro.com>
536       Roberto Di Cosmo <roberto@dicosmo.org>
537       Thomas Gazagnaire <thomas@gazagnaire.org>
538       Louis Gesbert <louis.gesbert@ocamlpro.com>
539       Fabrice Le Fessant <Fabrice.Le_fessant@inria.fr>
540       Anil Madhavapeddy <anil@recoil.org>
541       Guillem Rieu <guillem.rieu@ocamlpro.com>
542       Ralf Treinen <ralf.treinen@pps.jussieu.fr>
543       Frederic Tuong <tuong@users.gforge.inria.fr>
544

BUGS

546       Check bug reports at https://github.com/ocaml/opam/issues.
547
548
549
550Opam 2.1.5                                                             OPAM(1)
Impressum