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

NAME

6       opam-switch - Manage multiple installation prefixes.
7

SYNOPSIS

9       opam switch [OPTION]... [COMMAND] [ARG]...
10

DESCRIPTION

12       This command is used to manage "switches", which are independent
13       installation prefixes with their own compiler and sets of installed and
14       pinned packages. This is typically useful to have different versions of
15       the compiler available at once.
16
17       Use opam switch create to create a new switch, and opam switch set to
18       set the currently active switch. Without argument, lists installed
19       switches, with one switch argument, defaults to set.
20
21       Switch handles SWITCH can be either a plain name, for switches that
22       will be held inside ~/.opam, or a directory name, which in that case is
23       the directory where the switch prefix will be installed, as _opam. Opam
24       will automatically select a switch by that name found in the current
25       directory or its parents, unless OPAMSWITCH is set or --switch is
26       specified. When creating a directory switch, if package definitions are
27       found locally, the user is automatically prompted to install them after
28       the switch is created unless --no-install is specified.
29
30       opam switch set sets the default switch globally, but it is also
31       possible to select a switch in a given shell session, using the
32       environment. For that, use eval $(opam env --switch=SWITCH
33       --set-switch).
34

COMMANDS

36       Without argument, defaults to list.
37
38       SWITCH
39           With a SWITCH argument, defaults to set SWITCH.
40
41       create SWITCH [COMPILER]
42           Create a new switch, and install the given compiler there. SWITCH
43           can be a plain name, or a directory, absolute or relative, in which
44           case a local switch is created below the given directory. COMPILER,
45           if omitted, defaults to SWITCH if it is a plain name, unless
46           --packages or --empty is specified. When creating a local switch,
47           and none of these options are present, the compiler is chosen
48           according to the configuration default (see opam-init(1)). If the
49           chosen directory contains package definitions, a compatible
50           compiler is searched within the default selection, and the packages
51           will automatically get installed.
52
53       set SWITCH
54           Set the currently active switch, among the installed switches.
55
56       remove SWITCH
57           Remove the given switch from disk.
58
59       export FILE
60           Save the current switch state to a file. If --full is specified, it
61           includes the metadata of all installed packages
62
63       import FILE
64           Import a saved switch state. If --switch is specified and doesn't
65           point to an existing switch, the switch will be created for the
66           import.
67
68       reinstall [SWITCH]
69           Reinstall the given compiler switch and all its packages.
70
71       list
72           Lists installed switches.
73
74       list-available [PATTERN]
75           Lists base packages that can be used to create a new switch, i.e.
76           packages with the compiler flag set. If no pattern is supplied, all
77           versions are shown.
78
79       show
80           Prints the name of the current switch.
81
82       set-base PACKAGES
83           Sets the packages forming the immutable base for the selected
84           switch, overriding the current setting.
85
86       set-description STRING
87           Sets the description for the selected switch
88
89       link SWITCH [DIR]
90           Sets a local alias for a given switch, so that the switch gets
91           automatically selected whenever in that directory or a descendant.
92
93       install SWITCH
94           Deprecated alias for 'create'.
95

OPTIONS

97       -A COMP, --alias-of=COMP
98           This option is deprecated.
99
100       --deps-only
101           When creating a local switch in a project directory (i.e. a
102           directory containing opam package definitions), install the
103           dependencies of the project but not the project itself.
104
105       --description=STRING
106           Attach the given description to a switch when creating it. Use the
107           set-description subcommand to modify the description of an existing
108           switch.
109
110       --empty
111           Allow creating an empty (without compiler) switch.
112
113       --full
114           When exporting, include the metadata of all installed packages,
115           allowing to re-import even if they don't exist in the repositories
116           (the default is to include only the metadata of pinned packages).
117
118       -j JOBS, --jobs=JOBS
119           Set the maximal number of concurrent jobs to use. The default value
120           is calculated from the number of cores. You can also set it using
121           the $OPAMJOBS environment variable.
122
123       --no-autoinstall
124           This option is deprecated.
125
126       --no-install
127           When creating a local switch, don't look for any local package
128           definitions to install.
129
130       --no-switch
131           Don't automatically select newly installed switches.
132
133       --packages=PACKAGES
134           When installing a switch, explicitly define the set of packages to
135           set as the compiler.
136
137       --repositories=REPOS
138           When creating a new switch, use the given selection of repositories
139           instead of the default. REPOS should be a comma-separated list of
140           either already registered repository names (configured through e.g.
141           opam repository add --dont-select), or NAME=URL bindings, in which
142           case NAME should not be registered already to a different URL, and
143           the new repository will be registered. See opam repository for more
144           details. This option also affects list-available.
145
146       -s, --short
147           Output raw lists of names, one per line, skipping any details.
148

PACKAGE BUILD OPTIONS

150       -b, --keep-build-dir
151           Keep the build directories after compiling packages. This is
152           equivalent to setting $OPAMKEEPBUILDDIR to "true".
153
154       -d, --with-doc, --build-doc
155           Build the package documentation. This only affects packages listed
156           on the command-line. The --build-doc form is deprecated as this
157           does also installation. This is equivalent to setting $OPAMWITHDOC
158           (or the deprecated $OPAMBUILDDOC) to "true".
159
160       --dry-run
161           Simulate the command, but don't actually perform any changes. This
162           also can be set with environment variable $OPAMDEBUG.
163
164       --fake
165           This option registers the actions into the opam database, without
166           actually performing them. WARNING: This option is dangerous and
167           likely to break your opam environment. You probably want
168           `--dry-run'. You've been warned.
169
170       --ignore-constraints-on[=PACKAGES] (default=)
171           Forces opam to ignore version constraints on all dependencies to
172           the listed packages. This can be used to test compatibility, but
173           expect builds to break when using this. Note that version
174           constraints on optional dependencies and conflicts are unaffected.
175           This is equivalent to setting $OPAMIGNORECONSTRAINTS.
176
177       --inplace-build
178           When compiling a package which has its source bound to a local
179           directory, process the build and install actions directly in that
180           directory, rather than in a clean copy handled by opam. This only
181           affects packages that are explicitly listed on the command-line.
182           This is equivalent to setting $OPAMINPLACEBUILD to "true".
183
184       --locked[=SUFFIX] (default=locked)
185           In commands that use opam files found from pinned sources, if a
186           variant of the file with an added .SUFFIX extension is found (e.g.
187           foo.opam.locked besides foo.opam), that will be used instead. This
188           is typically useful to offer a more specific set of dependencies
189           and reproduce similar build contexts, hence the name. The opam lock
190           plugin can be used to generate such files, based on the versions of
191           the dependencies currently installed on the host. This is
192           equivalent to setting the $OPAMLOCKED environment variable. Note
193           that this option doesn't generally affect already pinned packages.
194
195       -m MAKE, --make=MAKE
196           Use MAKE as the default 'make' command. Deprecated: use opam config
197           set[-global] make MAKE instead. Has no effect if the make variable
198           is defined.
199
200       --no-checksums
201           Do not verify the checksum of downloaded archives.This is
202           equivalent to setting $OPAMNOCHECKSUMS to "true".
203
204       --require-checksums
205           Reject the installation of packages that don't provide a checksum
206           for the upstream archives. This is equivalent to setting
207           $OPAMREQUIRECHECKSUMS to "true".
208
209       --reuse-build-dir
210           Reuse existing build directories (kept by using --keep-build-dir),
211           instead of compiling from a fresh clone of the source. This can be
212           faster, but also lead to failures if the build systems of the
213           packages don't handle upgrades of dependencies well. This is
214           equivalent to setting $OPAMREUSEBUILDDIR to "true".
215
216       --show-actions
217           Call the solver and display the actions. Don't perform any changes.
218           This is equivalent to setting $OPAMSHOW.
219
220       --skip-updates
221           When running an install, upgrade or reinstall on source-pinned
222           packages, they are normally updated from their origin first. This
223           flag disables that behaviour and will keep them to their version in
224           cache. This is equivalent to setting $OPAMSKIPUPDATE.
225
226       -t, --with-test, --build-test
227           Build and run the package unit-tests. This only affects packages
228           listed on the command-line. The --build-test form is deprecated as
229           this also affects installation. This is equivalent to setting
230           $OPAMWITHTEST (or the deprecated $OPAMBUILDTEST) to "true".
231
232       --unlock-base
233           Allow changes to the packages set as switch base (typically, the
234           main compiler). Use with caution. This is equivalent to setting the
235           $OPAMUNLOCKBASE environment variable
236

COMMON OPTIONS

238       These options are common to all commands.
239
240       --best-effort
241           Don't fail if all requested packages can't be installed: try to
242           install as many as possible. Note that not all external solvers may
243           support this option (recent versions of aspcud or mccs should).
244           This is equivalent to setting $OPAMBESTEFFORT environment variable.
245
246       --color=WHEN
247           Colorize the output. WHEN must be one of `always', `never' or
248           `auto'.
249
250       --criteria=CRITERIA
251           Specify user preferences for dependency solving for this run.
252           Overrides both $OPAMCRITERIA and $OPAMUPGRADECRITERIA. For details
253           on the supported language, and the external solvers available, see
254           http://opam.ocaml.org/doc/External_solvers.html. A general guide to
255           using solver preferences can be found at
256           http://www.dicosmo.org/Articles/usercriteria.pdf.
257
258       --cudf=FILENAME
259           Debug option: Save the CUDF requests sent to the solver to
260           FILENAME-<n>.cudf.
261
262       --debug
263           Print debug message to stderr. This is equivalent to setting
264           $OPAMDEBUG to "true".
265
266       --debug-level=LEVEL
267           Like --debug, but allows specifying the debug level (--debug sets
268           it to 1). Equivalent to setting $OPAMDEBUG to a positive integer.
269
270       --git-version
271           Print the git version of opam, if set (i.e. you are using a
272           development version), and exit.
273
274       --help[=FMT] (default=auto)
275           Show this help in format FMT. The value FMT must be one of `auto',
276           `pager', `groff' or `plain'. With `auto', the format is `pager` or
277           `plain' whenever the TERM env var is `dumb' or undefined.
278
279       --ignore-pin-depends
280           Ignore extra pins required by packages that get pinned, either
281           manually through opam pin or through opam install DIR. This is
282           equivalent to setting IGNOREPINDEPENDS=true.
283
284       --json=FILENAME
285           Save the results of the opam run in a computer-readable file. If
286           the filename contains the character `%', it will be replaced by an
287           index that doesn't overwrite an existing file. Similar to setting
288           the $OPAMJSON variable.
289
290       --no-aspcud
291           Deprecated.
292
293       --no-auto-upgrade
294           When configuring or updating a repository that is written for an
295           earlier opam version (1.2), opam internally converts it to the
296           current format. This disables this behaviour. Note that
297           repositories should define their format version in a 'repo' file at
298           their root, or they will be assumed to be in the older format. It
299           is, in any case, preferable to upgrade the repositories manually
300           using opam admin upgrade [--mirror URL] when possible.
301
302       --no-self-upgrade
303           Opam will replace itself with a newer binary found at OPAMROOT/opam
304           if present. This disables this behaviour.
305
306       -q, --quiet
307           Disables --verbose.
308
309       --root=ROOT
310           Use ROOT as the current root path. This is equivalent to setting
311           $OPAMROOT to ROOT.
312
313       --safe, --readonly
314           Make sure nothing will be automatically updated or rewritten.
315           Useful for calling from completion scripts, for example. Will fail
316           whenever such an operation is needed ; also avoids waiting for
317           locks, skips interactive questions and overrides the $OPAMDEBUG
318           variable. This is equivalent to set environment variable $OPAMSAFE.
319
320       --solver=CMD
321           Specify the CUDF solver to use for resolving package installation
322           problems. This is either a predefined solver (this version of opam
323           supports builtin-mccs+lp(), builtin-mccs+glpk, aspcud, mccs,
324           aspcud-old, packup), or a custom command that should contain the
325           variables %{input}%, %{output}%, %{criteria}%, and optionally
326           %{timeout}%. This is equivalent to setting $OPAMEXTERNALSOLVER.
327
328       --strict
329           Fail whenever an error is found in a package definition or a
330           configuration file. The default is to continue silently if
331           possible.
332
333       --switch=SWITCH
334           Use SWITCH as the current compiler switch. This is equivalent to
335           setting $OPAMSWITCH to SWITCH.
336
337       --use-internal-solver
338           Disable any external solver, and use the built-in one (this
339           requires that opam has been compiled with a built-in solver). This
340           is equivalent to setting $OPAMNOASPCUD or $OPAMUSEINTERNALSOLVER.
341
342       -v, --verbose
343           Be more verbose. One -v shows all package commands, repeat to also
344           display commands called internally (e.g. tar, curl, patch etc.)
345           Repeating n times is equivalent to setting $OPAMVERBOSE to "n".
346
347       --version
348           Show version information.
349
350       -w, --working-dir
351           Whenever updating packages that are bound to a local,
352           version-controlled directory, update to the current working state
353           of their source instead of the last committed state, or the ref
354           they are pointing to. This only affects packages explicitly listed
355           on the command-line.It can also be set with $OPAMWORKINGDIR.
356
357       -y, --yes
358           Answer yes to all yes/no questions without prompting. This is
359           equivalent to setting $OPAMYES to "true".
360

ENVIRONMENT VARIABLES

362       Opam makes use of the environment variables listed here. Boolean
363       variables should be set to "0", "no", "false" or the empty string to
364       disable, "1", "yes" or "true" to enable.
365
366       OPAMALLPARENS surround all filters with parenthesis
367
368       OPAMAUTOREMOVE see remove option `--auto-remove`
369
370       OPAMBESTEFFORT see option `--best-effort`
371
372       OPAMBESTEFFORTPREFIXCRITERIA sets the string that must be prepended to
373       the criteria when the `--best-effort` option is set, and is expected to
374       maximise the `opam-query` property in the solution
375
376       OPAMCOLOR, when set to always or never, sets a default value for the
377       --color option.
378
379       OPAMCRITERIA specifies user preferences for dependency solving. The
380       default value depends on the solver version, use `config report` to
381       know the current setting. See also option --criteria
382
383       OPAMCUDFFILE file save the cudf graph to file-actions-explicit.dot
384
385       OPAMCURL can be used to select a given 'curl' program. See OPAMFETCH
386       for more options.
387
388       OPAMDEBUG see options `--debug' and `--debug-level'.
389
390       OPAMDOWNLOADJOBS sets the maximum number of simultaneous downloads.
391
392       OPAMDRYRUN see option `--dry-run`
393
394       OPAMEDITOR sets the editor to use for opam file editing, overrides
395       $EDITOR and $VISUAL
396
397       OPAMERRLOGLEN sets the number of log lines printed when a sub-process
398       fails. 0 to print all.
399
400       OPAMEXTERNALSOLVER see option `--solver'.
401
402       OPAMFAKE see option `--fake`
403
404       OPAMFETCH specifies how to download files: either `wget', `curl' or a
405       custom command where variables %{url}%, %{out}%, %{retry}%,
406       %{compress}% and %{checksum}% will be replaced. Overrides the
407       'download-command' value from the main config file.
408
409       OPAMFIXUPCRITERIA same as OPAMUPGRADECRITERIA, but specific to fixup
410
411       OPAMIGNORECONSTRAINTS see install option `--ignore-constraints-on`
412
413       OPAMIGNOREPINDEPENDS see option `--ignore-pin-depends`
414
415       OPAMJOBS sets the maximum number of parallel workers to run.
416
417       OPAMJSON log json output to the given file (use character `%' to index
418       the files)
419
420       OPAMLOCKED see install option `--locked`
421
422       OPAMLOGS logdir sets log directory, default is a temporary directory in
423       /tmp
424
425       OPAMMAKECMD set the system make command to use
426
427       OPAMNOAUTOUPGRADE disables automatic internal upgrade of repositories
428       in an earlier format to the current one, on 'update' or 'init'.
429
430       OPAMKEEPLOGS tells opam to not remove some temporary command logs and
431       some backups. This skips some finalisers and may also help to get more
432       reliable backtraces
433
434       OPAMLOCKRETRIES sets the number of tries after which opam gives up
435       acquiring its lock and fails. <= 0 means infinite wait.
436
437       OPAMMERGEOUT merge process outputs, stderr on stdout
438
439       OPAMNO answer no to any question asked.
440
441       OPAMNOASPCUD Deprecated.
442
443       OPAMNOCHECKSUMS enables option --no-checksums when available.
444
445       OPAMNOSELFUPGRADE see option `--no-self-upgrade'.
446
447       OPAMPINKINDAUTO sets whether version control systems should be detected
448       when pinning to a local path. Enabled by default since 1.3.0.
449
450       OPAMPRECISETRACKING fine grain tracking of directories
451
452       OPAMREQUIRECHECKSUMS Enables option `--require-checksums' when
453       available (e.g. for `opam install`).
454
455       OPAMRETRES sets the number of tries before failing downloads.
456
457       OPAMROOT see option `--root'. This is automatically set by `opam env
458       --root=DIR --set-root'.
459
460       OPAMROOTISOK don't complain when running as root.
461
462       OPAMSAFE see option `--safe'
463
464       OPAMSHOW see option `--show`
465
466       OPAMSKIPUPDATE see option `--skip-updates`
467
468       OPAMSKIPVERSIONCHECKS bypasses some version checks. Unsafe, for
469       compatibility testing only.
470
471       OPAMSOLVERTIMEOUT change the time allowance of the solver. Default is
472       60.0, set to 0 for unlimited. Note that all solvers may not support
473       this option.
474
475       OPAMSTATUSLINE display a dynamic status line showing what's currently
476       going on on the terminal. (one of one of `always', `never' or `auto')
477
478       OPAMSTATS display stats at the end of command
479
480       OPAMSTRICT fail on inconsistencies (file reading, switch import, etc.)
481
482       OPAMSWITCH see option `--switch'. Automatically set by `opam env
483       --switch=SWITCH --set-switch'.
484
485       OPAMUNLOCKBASE see install option `--unlock-base`
486
487       OPAMUPGRADECRITERIA specifies user preferences for dependency solving
488       when performing an upgrade. Overrides OPAMCRITERIA in upgrades if both
489       are set. See also option --criteria
490
491       OPAMUSEINTERNALSOLVER see option `--use-internal-solver'.
492
493       OPAMUSEOPENSSL force openssl use for hash computing
494
495       OPAMUTF8 use UTF8 characters in output (one of one of `always', `never'
496       or `auto'). By default `auto', which is determined from the locale).
497
498       OPAMUTF8MSGS use extended UTF8 characters (camels) in opam messages.
499       Implies OPAMUTF8. This is set by default on OSX only.
500
501       OPAMVALIDATIONHOOK hook if set, uses the `%{hook%}` command to validate
502       an opam repository update
503
504       OPAMVAR_var overrides the contents of the variable var when
505       substituting `%{var}%` strings in `opam` files.
506
507       OPAMVAR_package_var overrides the contents of the variable package:var
508       when substituting `%{package:var}%` strings in `opam` files.
509
510       OPAMVERBOSE see option `--verbose'.
511
512       OPAMWORKINGDIR see option `--working-dir`
513
514       OPAMYES see option `--yes'.
515

EXIT STATUS

517       As an exception to the following, the `exec' command returns 127 if the
518       command was not found or couldn't be executed, and the command's exit
519       value otherwise.
520
521       0   Success, or true for boolean queries.
522
523       1   False. Returned when a boolean return value is expected, e.g. when
524           running with --check, or for queries like opam lint.
525
526       2   Bad command-line arguments, or command-line arguments pointing to
527           an invalid context (e.g. file not following the expected format).
528
529       5   Not found. You requested something (package, version, repository,
530           etc.) that couldn't be found.
531
532       10  Aborted. The operation required confirmation, which wasn't given.
533
534       15  Could not acquire the locks required for the operation.
535
536       20  There is no solution to the user request. This can be caused by
537           asking to install two incompatible packages, for example.
538
539       30  Error in package definition, or other metadata files. Using
540           --strict raises this error more often.
541
542       31  Package script error. Some package operations were unsuccessful.
543           This may be an error in the packages or an incompatibility with
544           your system. This can be a partial error.
545
546       40  Sync error. Could not fetch some remotes from the network. This can
547           be a partial error.
548
549       50  Configuration error. Opam or system configuration doesn't allow
550           operation, and needs fixing.
551
552       60  Solver failure. The solver failed to return a sound answer. It can
553           be due to a broken external solver, or an error in solver
554           configuration.
555
556       99  Internal error. Something went wrong, likely due to a bug in opam
557           itself.
558
559       130 User interrupt. SIGINT was received, generally due to the user
560           pressing Ctrl-C.
561

FURTHER DOCUMENTATION

563       See https://opam.ocaml.org/doc.
564

AUTHORS

566       Vincent Bernardoff <vb@luminar.eu.org>
567       Raja Boujbel <raja.boujbel@ocamlpro.com>
568       Roberto Di Cosmo <roberto@dicosmo.org>
569       Thomas Gazagnaire <thomas@gazagnaire.org>
570       Louis Gesbert <louis.gesbert@ocamlpro.com>
571       Fabrice Le Fessant <Fabrice.Le_fessant@inria.fr>
572       Anil Madhavapeddy <anil@recoil.org>
573       Guillem Rieu <guillem.rieu@ocamlpro.com>
574       Ralf Treinen <ralf.treinen@pps.jussieu.fr>
575       Frederic Tuong <tuong@users.gforge.inria.fr>
576

BUGS

578       Check bug reports at https://github.com/ocaml/opam/issues.
579
580
581
582Opam 2.0.4                                                      OPAM-SWITCH(1)
Impressum