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 pin Pin a given package to a specific version or source.
56 reinstall
58 Reinstall a list of packages.
59 remove
61 Remove a list of packages.
62 repository
64 Manage opam repositories.
65 show
67 Display information about specific packages.
68 source
70 Get the source of an opam package.
71 switch
73 Manage multiple installation prefixes.
74 update
76 Update the list of available packages.
77 upgrade
79 Upgrade the installed package to latest version.
80 var Prints the value associated with a given variable
82
84 info
85 An alias for show.
86 remote
88 An alias for repository.
89 search
91 An alias for list --search.
92 uninstall
94 An alias for remove.
95 unpin
97 An alias for pin remove.
98
100 These options are common to all commands.
101 --best-effort
103 Don't fail if all requested packages can't be installed: try to
104 install as many as possible. Note that not all external solvers may
105 support this option (recent versions of aspcud or mccs should).
106 This is equivalent to setting $OPAMBESTEFFORT environment variable.
107 --color=WHEN
109 Colorize the output. WHEN must be one of `always', `never' or
110 `auto'.
111 --criteria=CRITERIA
113 Specify user preferences for dependency solving for this run.
114 Overrides both $OPAMCRITERIA and $OPAMUPGRADECRITERIA. For details
115 on the supported language, and the external solvers available, see
116 http://opam.ocaml.org/doc/External_solvers.html. A general guide to
117 using solver preferences can be found at
118 http://www.dicosmo.org/Articles/usercriteria.pdf.
119 --cudf=FILENAME
121 Debug option: Save the CUDF requests sent to the solver to
122 FILENAME-<n>.cudf.
123 --debug
125 Print debug message to stderr. This is equivalent to setting
126 $OPAMDEBUG to "true".
127 --debug-level=LEVEL
129 Like --debug, but allows specifying the debug level (--debug sets
130 it to 1). Equivalent to setting $OPAMDEBUG to a positive integer.
131 --git-version
133 Print the git version of opam, if set (i.e. you are using a
134 development version), and exit.
135 --help[=FMT] (default=auto)
137 Show this help in format FMT. The value FMT must be one of `auto',
138 `pager', `groff' or `plain'. With `auto', the format is `pager` or
139 `plain' whenever the TERM env var is `dumb' or undefined.
140 --ignore-pin-depends
142 Ignore extra pins required by packages that get pinned, either
143 manually through opam pin or through opam install DIR. This is
144 equivalent to setting IGNOREPINDEPENDS=true.
145 --json=FILENAME
147 Save the results of the opam run in a computer-readable file. If
148 the filename contains the character `%', it will be replaced by an
149 index that doesn't overwrite an existing file. Similar to setting
150 the $OPAMJSON variable.
151 --no-aspcud
153 Deprecated.
154 --no-auto-upgrade
156 When configuring or updating a repository that is written for an
157 earlier opam version (1.2), opam internally converts it to the
158 current format. This disables this behaviour. Note that
159 repositories should define their format version in a 'repo' file at
160 their root, or they will be assumed to be in the older format. It
161 is, in any case, preferable to upgrade the repositories manually
162 using opam admin upgrade [--mirror URL] when possible.
163 --no-self-upgrade
165 Opam will replace itself with a newer binary found at OPAMROOT/opam
166 if present. This disables this behaviour.
167 -q, --quiet
169 Disables --verbose.
170 --root=ROOT
172 Use ROOT as the current root path. This is equivalent to setting
173 $OPAMROOT to ROOT.
174 --safe, --readonly
176 Make sure nothing will be automatically updated or rewritten.
177 Useful for calling from completion scripts, for example. Will fail
178 whenever such an operation is needed ; also avoids waiting for
179 locks, skips interactive questions and overrides the $OPAMDEBUG
180 variable. This is equivalent to set environment variable $OPAMSAFE.
181 --solver=CMD
183 Specify the CUDF solver to use for resolving package installation
184 problems. This is either a predefined solver (this version of opam
185 supports builtin-mccs+lp(), builtin-mccs+glpk, aspcud, mccs,
186 aspcud-old, packup), or a custom command that should contain the
187 variables %{input}%, %{output}%, %{criteria}%, and optionally
188 %{timeout}%. This is equivalent to setting $OPAMEXTERNALSOLVER.
189 --strict
191 Fail whenever an error is found in a package definition or a
192 configuration file. The default is to continue silently if
193 possible.
194 --switch=SWITCH
196 Use SWITCH as the current compiler switch. This is equivalent to
197 setting $OPAMSWITCH to SWITCH.
198 --use-internal-solver
200 Disable any external solver, and use the built-in one (this
201 requires that opam has been compiled with a built-in solver). This
202 is equivalent to setting $OPAMNOASPCUD or $OPAMUSEINTERNALSOLVER.
203 -v, --verbose
205 Be more verbose. One -v shows all package commands, repeat to also
206 display commands called internally (e.g. tar, curl, patch etc.)
207 Repeating n times is equivalent to setting $OPAMVERBOSE to "n".
208 --version
210 Show version information.
211 -w, --working-dir
213 Whenever updating packages that are bound to a local,
214 version-controlled directory, update to the current working state
215 of their source instead of the last committed state, or the ref
216 they are pointing to. This only affects packages explicitly listed
217 on the command-line.It can also be set with $OPAMWORKINGDIR.
218 -y, --yes
220 Answer yes to all yes/no questions without prompting. This is
221 equivalent to setting $OPAMYES to "true".
222
224 Opam makes use of the environment variables listed here. Boolean
225 variables should be set to "0", "no", "false" or the empty string to
226 disable, "1", "yes" or "true" to enable.
227 OPAMALLPARENS surround all filters with parenthesis
229 OPAMAUTOREMOVE see remove option `--auto-remove`
231 OPAMBESTEFFORT see option `--best-effort`
233 OPAMBESTEFFORTPREFIXCRITERIA sets the string that must be prepended to
235 the criteria when the `--best-effort` option is set, and is expected to
236 maximise the `opam-query` property in the solution
237 OPAMCOLOR, when set to always or never, sets a default value for the
239 --color option.
240 OPAMCRITERIA specifies user preferences for dependency solving. The
242 default value depends on the solver version, use `config report` to
243 know the current setting. See also option --criteria
244 OPAMCUDFFILE file save the cudf graph to file-actions-explicit.dot
246 OPAMCURL can be used to select a given 'curl' program. See OPAMFETCH
248 for more options.
249 OPAMDEBUG see options `--debug' and `--debug-level'.
251 OPAMDOWNLOADJOBS sets the maximum number of simultaneous downloads.
253 OPAMDRYRUN see option `--dry-run`
255 OPAMEDITOR sets the editor to use for opam file editing, overrides
257 $EDITOR and $VISUAL
258 OPAMERRLOGLEN sets the number of log lines printed when a sub-process
260 fails. 0 to print all.
261 OPAMEXTERNALSOLVER see option `--solver'.
263 OPAMFAKE see option `--fake`
265 OPAMFETCH specifies how to download files: either `wget', `curl' or a
267 custom command where variables %{url}%, %{out}%, %{retry}%,
268 %{compress}% and %{checksum}% will be replaced. Overrides the
269 'download-command' value from the main config file.
270 OPAMFIXUPCRITERIA same as OPAMUPGRADECRITERIA, but specific to fixup
272 OPAMIGNORECONSTRAINTS see install option `--ignore-constraints-on`
274 OPAMIGNOREPINDEPENDS see option `--ignore-pin-depends`
276 OPAMJOBS sets the maximum number of parallel workers to run.
278 OPAMJSON log json output to the given file (use character `%' to index
280 the files)
281 OPAMLOCKED see install option `--locked`
283 OPAMLOGS logdir sets log directory, default is a temporary directory in
285 /tmp
286 OPAMMAKECMD set the system make command to use
288 OPAMNOAUTOUPGRADE disables automatic internal upgrade of repositories
290 in an earlier format to the current one, on 'update' or 'init'.
291 OPAMKEEPLOGS tells opam to not remove some temporary command logs and
293 some backups. This skips some finalisers and may also help to get more
294 reliable backtraces
295 OPAMLOCKRETRIES sets the number of tries after which opam gives up
297 acquiring its lock and fails. <= 0 means infinite wait.
298 OPAMMERGEOUT merge process outputs, stderr on stdout
300 OPAMNO answer no to any question asked.
302 OPAMNOASPCUD Deprecated.
304 OPAMNOCHECKSUMS enables option --no-checksums when available.
306 OPAMNOSELFUPGRADE see option `--no-self-upgrade'.
308 OPAMPINKINDAUTO sets whether version control systems should be detected
310 when pinning to a local path. Enabled by default since 1.3.0.
311 OPAMPRECISETRACKING fine grain tracking of directories
313 OPAMREQUIRECHECKSUMS Enables option `--require-checksums' when
315 available (e.g. for `opam install`).
316 OPAMRETRES sets the number of tries before failing downloads.
318 OPAMROOT see option `--root'. This is automatically set by `opam env
320 --root=DIR --set-root'.
321 OPAMROOTISOK don't complain when running as root.
323 OPAMSAFE see option `--safe'
325 OPAMSHOW see option `--show`
327 OPAMSKIPUPDATE see option `--skip-updates`
329 OPAMSKIPVERSIONCHECKS bypasses some version checks. Unsafe, for
331 compatibility testing only.
332 OPAMSOLVERTIMEOUT change the time allowance of the solver. Default is
334 60.0, set to 0 for unlimited. Note that all solvers may not support
335 this option.
336 OPAMSTATUSLINE display a dynamic status line showing what's currently
338 going on on the terminal. (one of one of `always', `never' or `auto')
339 OPAMSTATS display stats at the end of command
341 OPAMSTRICT fail on inconsistencies (file reading, switch import, etc.)
343 OPAMSWITCH see option `--switch'. Automatically set by `opam env
345 --switch=SWITCH --set-switch'.
346 OPAMUNLOCKBASE see install option `--unlock-base`
348 OPAMUPGRADECRITERIA specifies user preferences for dependency solving
350 when performing an upgrade. Overrides OPAMCRITERIA in upgrades if both
351 are set. See also option --criteria
352 OPAMUSEINTERNALSOLVER see option `--use-internal-solver'.
354 OPAMUSEOPENSSL force openssl use for hash computing
356 OPAMUTF8 use UTF8 characters in output (one of one of `always', `never'
358 or `auto'). By default `auto', which is determined from the locale).
359 OPAMUTF8MSGS use extended UTF8 characters (camels) in opam messages.
361 Implies OPAMUTF8. This is set by default on OSX only.
362 OPAMVALIDATIONHOOK hook if set, uses the `%{hook%}` command to validate
364 an opam repository update
365 OPAMVAR_var overrides the contents of the variable var when
367 substituting `%{var}%` strings in `opam` files.
368 OPAMVAR_package_var overrides the contents of the variable package:var
370 when substituting `%{package:var}%` strings in `opam` files.
371 OPAMVERBOSE see option `--verbose'.
373 OPAMWORKINGDIR see option `--working-dir`
375 OPAMYES see option `--yes'.
377
379 As an exception to the following, the `exec' command returns 127 if the
380 command was not found or couldn't be executed, and the command's exit
381 value otherwise.
382 0 Success, or true for boolean queries.
384 1 False. Returned when a boolean return value is expected, e.g. when
386 running with --check, or for queries like opam lint.
387 2 Bad command-line arguments, or command-line arguments pointing to
389 an invalid context (e.g. file not following the expected format).
390 5 Not found. You requested something (package, version, repository,
392 etc.) that couldn't be found.
393 10 Aborted. The operation required confirmation, which wasn't given.
395 15 Could not acquire the locks required for the operation.
397 20 There is no solution to the user request. This can be caused by
399 asking to install two incompatible packages, for example.
400 30 Error in package definition, or other metadata files. Using
402 --strict raises this error more often.
403 31 Package script error. Some package operations were unsuccessful.
405 This may be an error in the packages or an incompatibility with
406 your system. This can be a partial error.
407 40 Sync error. Could not fetch some remotes from the network. This can
409 be a partial error.
410 50 Configuration error. Opam or system configuration doesn't allow
412 operation, and needs fixing.
413 60 Solver failure. The solver failed to return a sound answer. It can
415 be due to a broken external solver, or an error in solver
416 configuration.
417 99 Internal error. Something went wrong, likely due to a bug in opam
419 itself.
420 130 User interrupt. SIGINT was received, generally due to the user
422 pressing Ctrl-C.
423
425 See https://opam.ocaml.org/doc.
426
428 Vincent Bernardoff <vb@luminar.eu.org>
429 Raja Boujbel <raja.boujbel@ocamlpro.com>
430 Roberto Di Cosmo <roberto@dicosmo.org>
431 Thomas Gazagnaire <thomas@gazagnaire.org>
432 Louis Gesbert <louis.gesbert@ocamlpro.com>
433 Fabrice Le Fessant <Fabrice.Le_fessant@inria.fr>
434 Anil Madhavapeddy <anil@recoil.org>
435 Guillem Rieu <guillem.rieu@ocamlpro.com>
436 Ralf Treinen <ralf.treinen@pps.jussieu.fr>
437 Frederic Tuong <tuong@users.gforge.inria.fr>
438
440 Check bug reports at https://github.com/ocaml/opam/issues.
441Opam 2.0.6 OPAM(1)