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

NAME

6       opam-install - Install a list of packages.
7

SYNOPSIS

9       opam install [OPTION]... [PACKAGES]...
10

DESCRIPTION

12       This command installs one or more packages inside the currently
13       selected switch (see opam switch). Once installed, you can remove
14       packages with opam remove, upgrade them with opam upgrade, and list
15       them with opam list. See opam pin as well to manage package versions,
16       reroute existing packages or add packages that are not defined in the
17       repositories.
18
19       All required dependencies of the selected packages will be installed
20       first. Any already installed packages having dependencies, or optional
21       dependencies to the changed packages will be recompiled. The proposed
22       solution may also imply removing incompatible or conflicting packages.
23
24       If paths are provided as argument instead of packages, they are assumed
25       to point to either project source directories containing one or more
26       package definitions (opam files), or directly to opam files. Then the
27       corresponding packages will be pinned to their local directory and
28       installed (unless --deps-only was specified).
29

ARGUMENTS

31       PACKAGES
32           List of package names, with an optional version or constraint, e.g
33           `pkg', `pkg.1.0' or `pkg>=0.5' ; or files or directory names
34           containing package description, with explicit directory (e.g.
35           `./foo.opam' or `.')
36

OPTIONS

38       --assume-built
39           For use on locally-pinned packages: assume they have already been
40           correctly built, and only run their installation instructions,
41           directly from their source directory. This skips the build
42           instructions and can be useful to install packages that are being
43           worked on. Implies --inplace-build. No locally-pinned packages will
44           be skipped.
45
46       --deps-only
47           Install all its dependencies, but don't actually install the
48           package.
49
50       --destdir=DIR
51           Copy the files installed by the given package within the current
52           opam switch below the prefix DIR, respecting their hierarchy, after
53           installation. Caution, calling this can overwrite, but never remove
54           files, even if they were installed by a previous use of --destdir,
55           e.g. on a previous version of the same package. See opam remove
56           --destdir to revert.
57
58       -j JOBS, --jobs=JOBS
59           Set the maximal number of concurrent jobs to use. The default value
60           is calculated from the number of cores. You can also set it using
61           the $OPAMJOBS environment variable.
62
63       --restore
64           Attempt to restore packages that were marked for installation but
65           have been removed due to errors
66
67       --set-root
68           Mark given packages as installed roots. This is the default for
69           newly manually-installed packages.
70
71       --unset-root
72           Mark given packages as "installed automatically".
73

PACKAGE BUILD OPTIONS

75       -b, --keep-build-dir
76           Keep the build directories after compiling packages. This is
77           equivalent to setting $OPAMKEEPBUILDDIR to "true".
78
79       -d, --with-doc, --build-doc
80           Build the package documentation. This only affects packages listed
81           on the command-line. The --build-doc form is deprecated as this
82           does also installation. This is equivalent to setting $OPAMWITHDOC
83           (or the deprecated $OPAMBUILDDOC) to "true".
84
85       --dry-run
86           Simulate the command, but don't actually perform any changes. This
87           also can be set with environment variable $OPAMDEBUG.
88
89       --fake
90           This option registers the actions into the opam database, without
91           actually performing them. WARNING: This option is dangerous and
92           likely to break your opam environment. You probably want
93           `--dry-run'. You've been warned.
94
95       --ignore-constraints-on[=PACKAGES] (default=)
96           Forces opam to ignore version constraints on all dependencies to
97           the listed packages. This can be used to test compatibility, but
98           expect builds to break when using this. Note that version
99           constraints on optional dependencies and conflicts are unaffected.
100           This is equivalent to setting $OPAMIGNORECONSTRAINTS.
101
102       --inplace-build
103           When compiling a package which has its source bound to a local
104           directory, process the build and install actions directly in that
105           directory, rather than in a clean copy handled by opam. This only
106           affects packages that are explicitly listed on the command-line.
107           This is equivalent to setting $OPAMINPLACEBUILD to "true".
108
109       --locked[=SUFFIX] (default=locked)
110           In commands that use opam files found from pinned sources, if a
111           variant of the file with an added .SUFFIX extension is found (e.g.
112           foo.opam.locked besides foo.opam), that will be used instead. This
113           is typically useful to offer a more specific set of dependencies
114           and reproduce similar build contexts, hence the name. The opam lock
115           plugin can be used to generate such files, based on the versions of
116           the dependencies currently installed on the host. This is
117           equivalent to setting the $OPAMLOCKED environment variable. Note
118           that this option doesn't generally affect already pinned packages.
119
120       -m MAKE, --make=MAKE
121           Use MAKE as the default 'make' command. Deprecated: use opam config
122           set[-global] make MAKE instead. Has no effect if the make variable
123           is defined.
124
125       --no-checksums
126           Do not verify the checksum of downloaded archives.This is
127           equivalent to setting $OPAMNOCHECKSUMS to "true".
128
129       --require-checksums
130           Reject the installation of packages that don't provide a checksum
131           for the upstream archives. This is equivalent to setting
132           $OPAMREQUIRECHECKSUMS to "true".
133
134       --reuse-build-dir
135           Reuse existing build directories (kept by using --keep-build-dir),
136           instead of compiling from a fresh clone of the source. This can be
137           faster, but also lead to failures if the build systems of the
138           packages don't handle upgrades of dependencies well. This is
139           equivalent to setting $OPAMREUSEBUILDDIR to "true".
140
141       --show-actions
142           Call the solver and display the actions. Don't perform any changes.
143           This is equivalent to setting $OPAMSHOW.
144
145       --skip-updates
146           When running an install, upgrade or reinstall on source-pinned
147           packages, they are normally updated from their origin first. This
148           flag disables that behaviour and will keep them to their version in
149           cache. This is equivalent to setting $OPAMSKIPUPDATE.
150
151       -t, --with-test, --build-test
152           Build and run the package unit-tests. This only affects packages
153           listed on the command-line. The --build-test form is deprecated as
154           this also affects installation. This is equivalent to setting
155           $OPAMWITHTEST (or the deprecated $OPAMBUILDTEST) to "true".
156
157       --unlock-base
158           Allow changes to the packages set as switch base (typically, the
159           main compiler). Use with caution. This is equivalent to setting the
160           $OPAMUNLOCKBASE environment variable
161

COMMON OPTIONS

163       These options are common to all commands.
164
165       --best-effort
166           Don't fail if all requested packages can't be installed: try to
167           install as many as possible. Note that not all external solvers may
168           support this option (recent versions of aspcud or mccs should).
169           This is equivalent to setting $OPAMBESTEFFORT environment variable.
170
171       --color=WHEN
172           Colorize the output. WHEN must be one of `always', `never' or
173           `auto'.
174
175       --criteria=CRITERIA
176           Specify user preferences for dependency solving for this run.
177           Overrides both $OPAMCRITERIA and $OPAMUPGRADECRITERIA. For details
178           on the supported language, and the external solvers available, see
179           http://opam.ocaml.org/doc/External_solvers.html. A general guide to
180           using solver preferences can be found at
181           http://www.dicosmo.org/Articles/usercriteria.pdf.
182
183       --cudf=FILENAME
184           Debug option: Save the CUDF requests sent to the solver to
185           FILENAME-<n>.cudf.
186
187       --debug
188           Print debug message to stderr. This is equivalent to setting
189           $OPAMDEBUG to "true".
190
191       --debug-level=LEVEL
192           Like --debug, but allows specifying the debug level (--debug sets
193           it to 1). Equivalent to setting $OPAMDEBUG to a positive integer.
194
195       --git-version
196           Print the git version of opam, if set (i.e. you are using a
197           development version), and exit.
198
199       --help[=FMT] (default=auto)
200           Show this help in format FMT. The value FMT must be one of `auto',
201           `pager', `groff' or `plain'. With `auto', the format is `pager` or
202           `plain' whenever the TERM env var is `dumb' or undefined.
203
204       --ignore-pin-depends
205           Ignore extra pins required by packages that get pinned, either
206           manually through opam pin or through opam install DIR. This is
207           equivalent to setting IGNOREPINDEPENDS=true.
208
209       --json=FILENAME
210           Save the results of the opam run in a computer-readable file. If
211           the filename contains the character `%', it will be replaced by an
212           index that doesn't overwrite an existing file. Similar to setting
213           the $OPAMJSON variable.
214
215       --no-aspcud
216           Deprecated.
217
218       --no-auto-upgrade
219           When configuring or updating a repository that is written for an
220           earlier opam version (1.2), opam internally converts it to the
221           current format. This disables this behaviour. Note that
222           repositories should define their format version in a 'repo' file at
223           their root, or they will be assumed to be in the older format. It
224           is, in any case, preferable to upgrade the repositories manually
225           using opam admin upgrade [--mirror URL] when possible.
226
227       --no-self-upgrade
228           Opam will replace itself with a newer binary found at OPAMROOT/opam
229           if present. This disables this behaviour.
230
231       -q, --quiet
232           Disables --verbose.
233
234       --root=ROOT
235           Use ROOT as the current root path. This is equivalent to setting
236           $OPAMROOT to ROOT.
237
238       --safe, --readonly
239           Make sure nothing will be automatically updated or rewritten.
240           Useful for calling from completion scripts, for example. Will fail
241           whenever such an operation is needed ; also avoids waiting for
242           locks, skips interactive questions and overrides the $OPAMDEBUG
243           variable. This is equivalent to set environment variable $OPAMSAFE.
244
245       --solver=CMD
246           Specify the CUDF solver to use for resolving package installation
247           problems. This is either a predefined solver (this version of opam
248           supports builtin-mccs+lp(), builtin-mccs+glpk, aspcud, mccs,
249           aspcud-old, packup), or a custom command that should contain the
250           variables %{input}%, %{output}%, %{criteria}%, and optionally
251           %{timeout}%. This is equivalent to setting $OPAMEXTERNALSOLVER.
252
253       --strict
254           Fail whenever an error is found in a package definition or a
255           configuration file. The default is to continue silently if
256           possible.
257
258       --switch=SWITCH
259           Use SWITCH as the current compiler switch. This is equivalent to
260           setting $OPAMSWITCH to SWITCH.
261
262       --use-internal-solver
263           Disable any external solver, and use the built-in one (this
264           requires that opam has been compiled with a built-in solver). This
265           is equivalent to setting $OPAMNOASPCUD or $OPAMUSEINTERNALSOLVER.
266
267       -v, --verbose
268           Be more verbose. One -v shows all package commands, repeat to also
269           display commands called internally (e.g. tar, curl, patch etc.)
270           Repeating n times is equivalent to setting $OPAMVERBOSE to "n".
271
272       --version
273           Show version information.
274
275       -w, --working-dir
276           Whenever updating packages that are bound to a local,
277           version-controlled directory, update to the current working state
278           of their source instead of the last committed state, or the ref
279           they are pointing to. This only affects packages explicitly listed
280           on the command-line.It can also be set with $OPAMWORKINGDIR.
281
282       -y, --yes
283           Answer yes to all yes/no questions without prompting. This is
284           equivalent to setting $OPAMYES to "true".
285

ENVIRONMENT VARIABLES

287       Opam makes use of the environment variables listed here. Boolean
288       variables should be set to "0", "no", "false" or the empty string to
289       disable, "1", "yes" or "true" to enable.
290
291       OPAMALLPARENS surround all filters with parenthesis
292
293       OPAMAUTOREMOVE see remove option `--auto-remove`
294
295       OPAMBESTEFFORT see option `--best-effort`
296
297       OPAMBESTEFFORTPREFIXCRITERIA sets the string that must be prepended to
298       the criteria when the `--best-effort` option is set, and is expected to
299       maximise the `opam-query` property in the solution
300
301       OPAMCOLOR, when set to always or never, sets a default value for the
302       --color option.
303
304       OPAMCRITERIA specifies user preferences for dependency solving. The
305       default value depends on the solver version, use `config report` to
306       know the current setting. See also option --criteria
307
308       OPAMCUDFFILE file save the cudf graph to file-actions-explicit.dot
309
310       OPAMCURL can be used to select a given 'curl' program. See OPAMFETCH
311       for more options.
312
313       OPAMDEBUG see options `--debug' and `--debug-level'.
314
315       OPAMDOWNLOADJOBS sets the maximum number of simultaneous downloads.
316
317       OPAMDRYRUN see option `--dry-run`
318
319       OPAMEDITOR sets the editor to use for opam file editing, overrides
320       $EDITOR and $VISUAL
321
322       OPAMERRLOGLEN sets the number of log lines printed when a sub-process
323       fails. 0 to print all.
324
325       OPAMEXTERNALSOLVER see option `--solver'.
326
327       OPAMFAKE see option `--fake`
328
329       OPAMFETCH specifies how to download files: either `wget', `curl' or a
330       custom command where variables %{url}%, %{out}%, %{retry}%,
331       %{compress}% and %{checksum}% will be replaced. Overrides the
332       'download-command' value from the main config file.
333
334       OPAMFIXUPCRITERIA same as OPAMUPGRADECRITERIA, but specific to fixup
335
336       OPAMIGNORECONSTRAINTS see install option `--ignore-constraints-on`
337
338       OPAMIGNOREPINDEPENDS see option `--ignore-pin-depends`
339
340       OPAMJOBS sets the maximum number of parallel workers to run.
341
342       OPAMJSON log json output to the given file (use character `%' to index
343       the files)
344
345       OPAMLOCKED see install option `--locked`
346
347       OPAMLOGS logdir sets log directory, default is a temporary directory in
348       /tmp
349
350       OPAMMAKECMD set the system make command to use
351
352       OPAMNOAUTOUPGRADE disables automatic internal upgrade of repositories
353       in an earlier format to the current one, on 'update' or 'init'.
354
355       OPAMKEEPLOGS tells opam to not remove some temporary command logs and
356       some backups. This skips some finalisers and may also help to get more
357       reliable backtraces
358
359       OPAMLOCKRETRIES sets the number of tries after which opam gives up
360       acquiring its lock and fails. <= 0 means infinite wait.
361
362       OPAMMERGEOUT merge process outputs, stderr on stdout
363
364       OPAMNO answer no to any question asked.
365
366       OPAMNOASPCUD Deprecated.
367
368       OPAMNOCHECKSUMS enables option --no-checksums when available.
369
370       OPAMNOSELFUPGRADE see option `--no-self-upgrade'.
371
372       OPAMPINKINDAUTO sets whether version control systems should be detected
373       when pinning to a local path. Enabled by default since 1.3.0.
374
375       OPAMPRECISETRACKING fine grain tracking of directories
376
377       OPAMREQUIRECHECKSUMS Enables option `--require-checksums' when
378       available (e.g. for `opam install`).
379
380       OPAMRETRES sets the number of tries before failing downloads.
381
382       OPAMROOT see option `--root'. This is automatically set by `opam env
383       --root=DIR --set-root'.
384
385       OPAMROOTISOK don't complain when running as root.
386
387       OPAMSAFE see option `--safe'
388
389       OPAMSHOW see option `--show`
390
391       OPAMSKIPUPDATE see option `--skip-updates`
392
393       OPAMSKIPVERSIONCHECKS bypasses some version checks. Unsafe, for
394       compatibility testing only.
395
396       OPAMSOLVERTIMEOUT change the time allowance of the solver. Default is
397       60.0, set to 0 for unlimited. Note that all solvers may not support
398       this option.
399
400       OPAMSTATUSLINE display a dynamic status line showing what's currently
401       going on on the terminal. (one of one of `always', `never' or `auto')
402
403       OPAMSTATS display stats at the end of command
404
405       OPAMSTRICT fail on inconsistencies (file reading, switch import, etc.)
406
407       OPAMSWITCH see option `--switch'. Automatically set by `opam env
408       --switch=SWITCH --set-switch'.
409
410       OPAMUNLOCKBASE see install option `--unlock-base`
411
412       OPAMUPGRADECRITERIA specifies user preferences for dependency solving
413       when performing an upgrade. Overrides OPAMCRITERIA in upgrades if both
414       are set. See also option --criteria
415
416       OPAMUSEINTERNALSOLVER see option `--use-internal-solver'.
417
418       OPAMUSEOPENSSL force openssl use for hash computing
419
420       OPAMUTF8 use UTF8 characters in output (one of one of `always', `never'
421       or `auto'). By default `auto', which is determined from the locale).
422
423       OPAMUTF8MSGS use extended UTF8 characters (camels) in opam messages.
424       Implies OPAMUTF8. This is set by default on OSX only.
425
426       OPAMVALIDATIONHOOK hook if set, uses the `%{hook%}` command to validate
427       an opam repository update
428
429       OPAMVAR_var overrides the contents of the variable var when
430       substituting `%{var}%` strings in `opam` files.
431
432       OPAMVAR_package_var overrides the contents of the variable package:var
433       when substituting `%{package:var}%` strings in `opam` files.
434
435       OPAMVERBOSE see option `--verbose'.
436
437       OPAMWORKINGDIR see option `--working-dir`
438
439       OPAMYES see option `--yes'.
440

EXIT STATUS

442       As an exception to the following, the `exec' command returns 127 if the
443       command was not found or couldn't be executed, and the command's exit
444       value otherwise.
445
446       0   Success, or true for boolean queries.
447
448       1   False. Returned when a boolean return value is expected, e.g. when
449           running with --check, or for queries like opam lint.
450
451       2   Bad command-line arguments, or command-line arguments pointing to
452           an invalid context (e.g. file not following the expected format).
453
454       5   Not found. You requested something (package, version, repository,
455           etc.) that couldn't be found.
456
457       10  Aborted. The operation required confirmation, which wasn't given.
458
459       15  Could not acquire the locks required for the operation.
460
461       20  There is no solution to the user request. This can be caused by
462           asking to install two incompatible packages, for example.
463
464       30  Error in package definition, or other metadata files. Using
465           --strict raises this error more often.
466
467       31  Package script error. Some package operations were unsuccessful.
468           This may be an error in the packages or an incompatibility with
469           your system. This can be a partial error.
470
471       40  Sync error. Could not fetch some remotes from the network. This can
472           be a partial error.
473
474       50  Configuration error. Opam or system configuration doesn't allow
475           operation, and needs fixing.
476
477       60  Solver failure. The solver failed to return a sound answer. It can
478           be due to a broken external solver, or an error in solver
479           configuration.
480
481       99  Internal error. Something went wrong, likely due to a bug in opam
482           itself.
483
484       130 User interrupt. SIGINT was received, generally due to the user
485           pressing Ctrl-C.
486

FURTHER DOCUMENTATION

488       See https://opam.ocaml.org/doc.
489

AUTHORS

491       Vincent Bernardoff <vb@luminar.eu.org>
492       Raja Boujbel <raja.boujbel@ocamlpro.com>
493       Roberto Di Cosmo <roberto@dicosmo.org>
494       Thomas Gazagnaire <thomas@gazagnaire.org>
495       Louis Gesbert <louis.gesbert@ocamlpro.com>
496       Fabrice Le Fessant <Fabrice.Le_fessant@inria.fr>
497       Anil Madhavapeddy <anil@recoil.org>
498       Guillem Rieu <guillem.rieu@ocamlpro.com>
499       Ralf Treinen <ralf.treinen@pps.jussieu.fr>
500       Frederic Tuong <tuong@users.gforge.inria.fr>
501

BUGS

503       Check bug reports at https://github.com/ocaml/opam/issues.
504
505
506
507Opam 2.0.4                                                     OPAM-INSTALL(1)
Impressum