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 --color=WHEN
108 Colorize the output. WHEN must be one of `always', `never' or
109 `auto'.
110 --criteria=CRITERIA
112 Specify user preferences for dependency solving for this run.
113 Overrides both $OPAMCRITERIA and $OPAMUPGRADECRITERIA. For details
114 on the supported language, and the external solvers available, see
115 http://opam.ocaml.org/doc/Specifying_Solver_Preferences.html. A
116 general guide to using solver preferences can be found at
117 http://www.dicosmo.org/Articles/usercriteria.pdf.
118 --cudf=FILENAME
120 Debug option: Save the CUDF requests sent to the solver to
121 FILENAME-<n>.cudf.
122 --debug
124 Print debug message to stderr. This is equivalent to setting
125 $OPAMDEBUG to "true".
126 --debug-level=LEVEL
128 Like --debug, but allows specifying the debug level (--debug sets
129 it to 1). Equivalent to setting $OPAMDEBUG to a positive integer.
130 --git-version
132 Print the git version of opam, if set (i.e. you are using a
133 development version), and exit.
134 --help[=FMT] (default=auto)
136 Show this help in format FMT. The value FMT must be one of `auto',
137 `pager', `groff' or `plain'. With `auto', the format is `pager` or
138 `plain' whenever the TERM env var is `dumb' or undefined.
139 --ignore-pin-depends
141 Ignore extra pins required by packages that get pinned, either
142 manually through opam pin or through opam install DIR. This is
143 equivalent to setting IGNOREPINDEPENDS=true.
144 --json=FILENAME
146 Save the results of the opam run in a computer-readable file. If
147 the filename contains the character `%', it will be replaced by an
148 index that doesn't overwrite an existing file. Similar to setting
149 the $OPAMJSON variable.
150 --no-auto-upgrade
152 When configuring or updating a repository that is written for an
153 earlier opam version (1.2), opam internally converts it to the
154 current format. This disables this behaviour. Note that
155 repositories should define their format version in a 'repo' file at
156 their root, or they will be assumed to be in the older format. It
157 is, in any case, preferable to upgrade the repositories manually
158 using opam admin upgrade [--mirror URL] when possible.
159 --no-self-upgrade
161 Opam will replace itself with a newer binary found at OPAMROOT/opam
162 if present. This disables this behaviour.
163 -q, --quiet
165 Disables --verbose.
166 --root=ROOT
168 Use ROOT as the current root path. This is equivalent to setting
169 $OPAMROOT to ROOT.
170 --safe, --readonly
172 Make sure nothing will be automatically updated or rewritten.
173 Useful for calling from completion scripts, for example. Will fail
174 whenever such an operation is needed ; also avoids waiting for
175 locks, skips interactive questions and overrides the $OPAMDEBUG
176 variable.
177 --solver=CMD
179 Specify the CUDF solver to use for resolving package installation
180 problems. This is either a predefined solver (this version of opam
181 supports builtin-mccs+lp(), builtin-mccs+glpk, aspcud, mccs,
182 aspcud-old, packup), or a custom command that should contain the
183 variables %{input}%, %{output}%, %{criteria}%, and optionally
184 %{timeout}%.
185 --strict
187 Fail whenever an error is found in a package definition or a
188 configuration file. The default is to continue silently if
189 possible.
190 --switch=SWITCH
192 Use SWITCH as the current compiler switch. This is equivalent to
193 setting $OPAMSWITCH to SWITCH.
194 --use-internal-solver, --no-aspcud
196 Disable any external solver, and use the built-in one (this
197 requires that opam has been compiled with a built-in solver).
198 -v, --verbose
200 Be more verbose. One -v shows all package commands, repeat to also
201 display commands called internally (e.g. tar, curl, patch etc.)
202 Repeating n times is equivalent to setting $OPAMVERBOSE to "n".
203 --version
205 Show version information.
206 -w, --working-dir
208 Whenever updating packages that are bound to a local,
209 version-controlled directory, update to the current working state
210 of their source instead of the last committed state, or the ref
211 they are pointing to. This only affects packages explicitly listed
212 on the command-line.
213 -y, --yes
215 Answer yes to all yes/no questions without prompting. This is
216 equivalent to setting $OPAMYES to "true".
217
219 Opam makes use of the environment variables listed here. Boolean
220 variables should be set to "0", "no", "false" or the empty string to
221 disable, "1", "yes" or "true" to enable.
222 OPAMCOLOR, when set to always or never, sets a default value for the
224 --color option.
225 OPAMCRITERIA specifies user preferences for dependency solving. The
227 default value depends on the solver version, use `config report` to
228 know the current setting. See also option --criteria
229 OPAMCURL can be used to select a given 'curl' program. See OPAMFETCH
231 for more options.
232 OPAMDEBUG see options `--debug' and `--debug-level'.
234 OPAMDOWNLOADJOBS sets the maximum number of simultaneous downloads.
236 OPAMERRLOGLEN sets the number of log lines printed when a sub-process
238 fails. 0 to print all.
239 OPAMEXTERNALSOLVER see option `--solver'.
241 OPAMFETCH specifies how to download files: either `wget', `curl' or a
243 custom command where variables %{url}%, %{out}%, %{retry}%,
244 %{compress}% and %{checksum}% will be replaced. Overrides the
245 'download-command' value from the main config file.
246 OPAMJOBS sets the maximum number of parallel workers to run.
248 OPAMJSON log json output to the given file (use character `%' to index
250 the files)
251 OPAMLOCK see option `--lock'.
253 OPAMNOAUTOUPGRADE disables automatic internal upgrade of repositories
255 in an earlier format to the current one, on 'update' or 'init'.
256 OPAMKEEPLOGS tells opam to not remove some temporary command logs and
258 some backups. This skips some finalisers and may also help to get more
259 reliable backtraces
260 OPAMLOCKRETRIES sets the number of tries after which OPAM gives up
262 acquiring its lock and fails. <= 0 means infinite wait.
263 OPAMNO answer no to any question asked.
265 OPAMNOASPCUD see option `--no-aspcud'.
267 OPAMNOSELFUPGRADE see option `--no-self-upgrade'.
269 OPAMPINKINDAUTO sets whether version control systems should be detected
271 when pinning to a local path. Enabled by default since 1.3.0.
272 OPAMREQUIRECHECKSUMS Enables option `--require-checksums' when
274 available (e.g. for `opam install`).
275 OPAMRETRY sets the number of tries before failing downloads.
277 OPAMROOT see option `--root'. This is automatically set by `opam env
279 --root=DIR --set-root'.
280 OPAMROOTISOK don't complain when running as root.
282 OPAMSAFE see option `--safe'
284 OPAMSKIPVERSIONCHECKS bypasses some version checks. Unsafe, for
286 compatibility testing only.
287 OPAMSOLVERTIMEOUT change the time allowance of the solver. Default is
289 60.0, set to 0 for unlimited. Note that all solvers may not support
290 this option.
291 OPAMSTATUSLINE display a dynamic status line showing what's currently
293 going on on the terminal. (one of one of `always', `never' or `auto')
294 OPAMSWITCH see option `--switch'. Automatically set by `opam env
296 --switch=SWITCH --set-switch'.
297 OPAMUPGRADECRITERIA specifies user preferences for dependency solving
299 when performing an upgrade. Overrides OPAMCRITERIA in upgrades if both
300 are set. See also option --criteria
301 OPAMUSEINTERNALSOLVER see option `--use-internal-solver'.
303 OPAMUTF8 use UTF8 characters in output (one of one of `always', `never'
305 or `auto'). By default `auto', which is determined from the locale).
306 OPAMUTF8MSGS use extended UTF8 characters (camels) in opam messages.
308 Implies OPAMUTF8. This is set by default on OSX only.
309 OPAMVAR_var overrides the contents of the variable var when
311 substituting `%{var}%` strings in `opam` files.
312 OPAMVAR_package_var overrides the contents of the variable package:var
314 when substituting `%{package:var}%` strings in `opam` files.
315 OPAMVERBOSE see option `--verbose'.
317 OPAMYES see option `--yes'.
319
321 As an exception to the following, the `exec' command returns 127 if the
322 command was not found or couldn't be executed, and the command's exit
323 value otherwise.
324 0 Success, or true for boolean queries.
326 1 False. Returned when a boolean return value is expected, e.g. when
328 running with --check, or for queries like opam lint.
329 2 Bad command-line arguments, or command-line arguments pointing to
331 an invalid context (e.g. file not following the expected format).
332 5 Not found. You requested something (package, version, repository,
334 etc.) that couldn't be found.
335 10 Aborted. The operation required confirmation, which wasn't given.
337 15 Could not acquire the locks required for the operation.
339 20 There is no solution to the user request. This can be caused by
341 asking to install two incompatible packages, for example.
342 30 Error in package definition, or other metadata files. Using
344 --strict raises this error more often.
345 31 Package script error. Some package operations were unsuccessful.
347 This may be an error in the packages or an incompatibility with
348 your system. This can be a partial error.
349 40 Sync error. Could not fetch some remotes from the network. This can
351 be a partial error.
352 50 Configuration error. Opam or system configuration doesn't allow
354 operation, and needs fixing.
355 60 Solver failure. The solver failed to return a sound answer. It can
357 be due to a broken external solver, or an error in solver
358 configuration.
359 99 Internal error. Something went wrong, likely due to a bug in opam
361 itself.
362 130 User interrupt. SIGINT was received, generally due to the user
364 pressing Ctrl-C.
365
367 See https://opam.ocaml.org/doc.
368
370 Vincent Bernardoff <vb@luminar.eu.org>
371 Raja Boujbel <raja.boujbel@ocamlpro.com>
372 Roberto Di Cosmo <roberto@dicosmo.org>
373 Thomas Gazagnaire <thomas@gazagnaire.org>
374 Louis Gesbert <louis.gesbert@ocamlpro.com>
375 Fabrice Le Fessant <Fabrice.Le_fessant@inria.fr>
376 Anil Madhavapeddy <anil@recoil.org>
377 Guillem Rieu <guillem.rieu@ocamlpro.com>
378 Ralf Treinen <ralf.treinen@pps.jussieu.fr>
379 Frederic Tuong <tuong@users.gforge.inria.fr>
380
382 Check bug reports at https://github.com/ocaml/opam/issues.
383Opam 2.0.1 opam(1)