Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
opam-switch(1)			  Opam Manual			opam-switch(1)

       opam-switch - Manage multiple installation prefixes.

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

       This command is used to manage "switches", which	are independent
       installation prefixes with their	own compiler and sets of installed and
       pinned packages.	This is	typically useful to have different versions of
       the compiler available at once.

       Use opam	switch create to create	a new switch, and opam switch set to
       set the currently active	switch.	Without	argument, lists	installed
       switches, with one switch argument, defaults to set.

       Switch handles SWITCH can be either a plain name, for switches that
       will be held inside ~/.opam, or a directory name, which in that case is
       the directory where the switch prefix will be installed,	as _opam. Opam
       will automatically select a switch by that name found in	the current
       directory or its	parents, unless	OPAMSWITCH is set or --switch is
       specified. When creating	a directory switch, if package definitions are
       found locally, the user is automatically	prompted to install them after
       the switch is created unless --no-install is specified.

       opam switch set sets the	default	switch globally, but it	is also
       possible	to select a switch in a	given shell session, using the
       environment. For	that, use eval $(opam env --switch=SWITCH

       Without argument, defaults to list.

	   With	a SWITCH argument, defaults to set SWITCH.

       create SWITCH [COMPILER]
	   Create a new	switch,	and install the	given compiler there. SWITCH
	   can be a plain name,	or a directory,	absolute or relative, in which
	   case	a local	switch is created below	the given directory. COMPILER,
	   if omitted, defaults	to SWITCH if it	is a plain name, unless
	   --packages or --empty is specified. When creating a local switch,
	   and none of these options are present, the compiler is chosen
	   according to	the configuration default (see opam-init(1)). If the
	   chosen directory contains package definitions, a compatible
	   compiler is searched	within the default selection, and the packages
	   will	automatically get installed.

       set SWITCH
	   Set the currently active switch, among the installed	switches.

       remove SWITCH
	   Remove the given switch from	disk.

       export FILE
	   Save	the current switch state to a file. If --full is specified, it
	   includes the	metadata of all	installed packages

       import FILE
	   Import a saved switch state.	If --switch is specified and doesn't
	   point to an existing	switch,	the switch will	be created for the

       reinstall [SWITCH]
	   Reinstall the given compiler	switch and all its packages.

	   Lists installed switches.

       list-available [PATTERN]
	   Lists base packages that can	be used	to create a new	switch,	i.e.
	   packages with the compiler flag set.	If no pattern is supplied, all
	   versions are	shown.

	   Prints the name of the current switch.

       set-base	PACKAGES
	   Sets	the packages forming the immutable base	for the	selected
	   switch, overriding the current setting.

       set-description STRING
	   Sets	the description	for the	selected switch

       link SWITCH [DIR]
	   Sets	a local	alias for a given switch, so that the switch gets
	   automatically selected whenever in that directory or	a descendant.

       install SWITCH
	   Deprecated alias for	'create'.

       -A COMP,	--alias-of=COMP
	   This	option is deprecated.

	   When	creating a local switch	in a project directory (i.e. a
	   directory containing	opam package definitions), install the
	   dependencies	of the project but not the project itself.

	   Attach the given description	to a switch when creating it. Use the
	   set-description subcommand to modify	the description	of an existing

	   Allow creating an empty (without compiler) switch.

	   When	exporting, include the metadata	of all installed packages,
	   allowing to re-import even if they don't exist in the repositories
	   (the	default	is to include only the metadata	of pinned packages).

       -j JOBS,	--jobs=JOBS
	   Set the maximal number of concurrent	jobs to	use. The default value
	   is calculated from the number of cores. You can also	set it using
	   the $OPAMJOBS environment variable.

	   This	option is deprecated.

	   When	creating a local switch, don't look for	any local package
	   definitions to install.

	   Don't automatically select newly installed switches.

	   When	installing a switch, explicitly	define the set of packages to
	   set as the compiler.

	   When	creating a new switch, use the given selection of repositories
	   instead of the default. REPOS should	be a comma-separated list of
	   either already registered repository	names (configured through e.g.
	   opam	repository add --dont-select), or NAME=URL bindings, in	which
	   case	NAME should not	be registered already to a different URL, and
	   the new repository will be registered. See opam repository for more
	   details. This option	also affects list-available.

       -s, --short
	   Output raw lists of names, one per line, skipping any details.

       -b, --keep-build-dir
	   Keep	the build directories after compiling packages.	This is
	   equivalent to setting $OPAMKEEPBUILDDIR to "true".

       -d, --with-doc, --build-doc
	   Build the package documentation. This only affects packages listed
	   on the command-line.	The --build-doc	form is	deprecated as this
	   does	also installation. This	is equivalent to setting $OPAMWITHDOC
	   (or the deprecated $OPAMBUILDDOC) to	"true".

	   Simulate the	command, but don't actually perform any	changes. This
	   also	can be set with	environment variable $OPAMDEBUG.

	   This	option registers the actions into the opam database, without
	   actually performing them. WARNING: This option is dangerous and
	   likely to break your	opam environment. You probably want
	   `--dry-run'.	You've been warned.

       --ignore-constraints-on[=PACKAGES] (default=)
	   Forces opam to ignore version constraints on	all dependencies to
	   the listed packages.	This can be used to test compatibility,	but
	   expect builds to break when using this. Note	that version
	   constraints on optional dependencies	and conflicts are unaffected.
	   This	is equivalent to setting $OPAMIGNORECONSTRAINTS.

	   When	compiling a package which has its source bound to a local
	   directory, process the build	and install actions directly in	that
	   directory, rather than in a clean copy handled by opam. This	only
	   affects packages that are explicitly	listed on the command-line.
	   This	is equivalent to setting $OPAMINPLACEBUILD to "true".

       --locked[=SUFFIX] (default=locked)
	   In commands that use	opam files found from pinned sources, if a
	   variant of the file with an added .SUFFIX extension is found	(e.g.
	   foo.opam.locked besides foo.opam), that will	be used	instead. This
	   is typically	useful to offer	a more specific	set of dependencies
	   and reproduce similar build contexts, hence the name. The opam lock
	   plugin can be used to generate such files, based on the versions of
	   the dependencies currently installed	on the host. This is
	   equivalent to setting the $OPAMLOCKED environment variable. Note
	   that	this option doesn't generally affect already pinned packages.

       -m MAKE,	--make=MAKE
	   Use MAKE as the default 'make' command. Deprecated: use opam	config
	   set[-global]	make MAKE instead. Has no effect if the	make variable
	   is defined.

	   Do not verify the checksum of downloaded archives.This is
	   equivalent to setting $OPAMNOCHECKSUMS to "true".

	   Reject the installation of packages that don't provide a checksum
	   for the upstream archives. This is equivalent to setting

	   Reuse existing build	directories (kept by using --keep-build-dir),
	   instead of compiling	from a fresh clone of the source. This can be
	   faster, but also lead to failures if	the build systems of the
	   packages don't handle upgrades of dependencies well.	This is
	   equivalent to setting $OPAMREUSEBUILDDIR to "true".

	   Call	the solver and display the actions. Don't perform any changes.
	   This	is equivalent to setting $OPAMSHOW.

	   When	running	an install, upgrade or reinstall on source-pinned
	   packages, they are normally updated from their origin first.	This
	   flag	disables that behaviour	and will keep them to their version in
	   cache. This is equivalent to	setting	$OPAMSKIPUPDATE.

       -t, --with-test,	--build-test
	   Build and run the package unit-tests. This only affects packages
	   listed on the command-line. The --build-test	form is	deprecated as
	   this	also affects installation. This	is equivalent to setting
	   $OPAMWITHTEST (or the deprecated $OPAMBUILDTEST) to "true".

	   Allow changes to the	packages set as	switch base (typically,	the
	   main	compiler). Use with caution. This is equivalent	to setting the
	   $OPAMUNLOCKBASE environment variable

       These options are common	to all commands.

	   Don't fail if all requested packages	can't be installed: try	to
	   install as many as possible.	Note that not all external solvers may
	   support this	option (recent versions	of aspcud or mccs should).
	   This	is equivalent to setting $OPAMBESTEFFORT environment variable.

	   Colorize the	output.	WHEN must be one of `always', `never' or

	   Specify user	preferences for	dependency solving for this run.
	   Overrides both $OPAMCRITERIA	and $OPAMUPGRADECRITERIA. For details
	   on the supported language, and the external solvers available, see A general guide to
	   using solver	preferences can	be found at

	   Debug option: Save the CUDF requests	sent to	the solver to

	   Print debug message to stderr. This is equivalent to	setting
	   $OPAMDEBUG to "true".

	   Like	--debug, but allows specifying the debug level (--debug	sets
	   it to 1). Equivalent	to setting $OPAMDEBUG to a positive integer.

	   Print the git version of opam, if set (i.e. you are using a
	   development version), and exit.

       --help[=FMT] (default=auto)
	   Show	this help in format FMT. The value FMT must be one of `auto',
	   `pager', `groff' or `plain'.	With `auto', the format	is `pager` or
	   `plain' whenever the	TERM env var is	`dumb' or undefined.

	   Ignore extra	pins required by packages that get pinned, either
	   manually through opam pin or	through	opam install DIR. This is
	   equivalent to setting IGNOREPINDEPENDS=true.

	   Save	the results of the opam	run in a computer-readable file. If
	   the filename	contains the character `%', it will be replaced	by an
	   index that doesn't overwrite	an existing file. Similar to setting
	   the $OPAMJSON variable.


	   When	configuring or updating	a repository that is written for an
	   earlier opam	version	(1.2), opam internally converts	it to the
	   current format. This	disables this behaviour. Note that
	   repositories	should define their format version in a	'repo' file at
	   their root, or they will be assumed to be in	the older format. It
	   is, in any case, preferable to upgrade the repositories manually
	   using opam admin upgrade [--mirror URL] when	possible.

	   Opam	will replace itself with a newer binary	found at OPAMROOT/opam
	   if present. This disables this behaviour.

       -q, --quiet
	   Disables --verbose.

	   Use ROOT as the current root	path. This is equivalent to setting

       --safe, --readonly
	   Make	sure nothing will be automatically updated or rewritten.
	   Useful for calling from completion scripts, for example. Will fail
	   whenever such an operation is needed	; also avoids waiting for
	   locks, skips	interactive questions and overrides the	$OPAMDEBUG
	   variable. This is equivalent	to set environment variable $OPAMSAFE.

	   Specify the CUDF solver to use for resolving	package	installation
	   problems. This is either a predefined solver	(this version of opam
	   supports builtin-mccs+lp(), builtin-mccs+glpk, aspcud, mccs,
	   aspcud-old, packup),	or a custom command that should	contain	the
	   variables %{input}%,	%{output}%, %{criteria}%, and optionally
	   %{timeout}%.	This is	equivalent to setting $OPAMEXTERNALSOLVER.

	   Fail	whenever an error is found in a	package	definition or a
	   configuration file. The default is to continue silently if

	   Use SWITCH as the current compiler switch. This is equivalent to
	   setting $OPAMSWITCH to SWITCH.

	   Disable any external	solver,	and use	the built-in one (this
	   requires that opam has been compiled	with a built-in	solver). This
	   is equivalent to setting $OPAMNOASPCUD or $OPAMUSEINTERNALSOLVER.

       -v, --verbose
	   Be more verbose. One	-v shows all package commands, repeat to also
	   display commands called internally (e.g. tar, curl, patch etc.)
	   Repeating n times is	equivalent to setting $OPAMVERBOSE to "n".

	   Show	version	information.

       -w, --working-dir
	   Whenever updating packages that are bound to	a local,
	   version-controlled directory, update	to the current working state
	   of their source instead of the last committed state,	or the ref
	   they	are pointing to. This only affects packages explicitly listed
	   on the command-line.It can also be set with $OPAMWORKINGDIR.

       -y, --yes
	   Answer yes to all yes/no questions without prompting. This is
	   equivalent to setting $OPAMYES to "true".

       Opam makes use of the environment variables listed here.	Boolean
       variables should	be set to "0", "no", "false" or	the empty string to
       disable,	"1", "yes" or "true" to	enable.

       OPAMALLPARENS surround all filters with parenthesis

       OPAMAUTOREMOVE see remove option	`--auto-remove`

       OPAMBESTEFFORT see option `--best-effort`

       OPAMBESTEFFORTPREFIXCRITERIA sets the string that must be prepended to
       the criteria when the `--best-effort` option is set, and	is expected to
       maximise	the `opam-query` property in the solution

       OPAMCOLOR, when set to always or	never, sets a default value for	the
       --color option.

       OPAMCRITERIA specifies user preferences for dependency solving. The
       default value depends on	the solver version, use	`config	report`	to
       know the	current	setting. See also option --criteria

       OPAMCUDFFILE file save the cudf graph to

       OPAMCURL	can be used to select a	given 'curl' program. See OPAMFETCH
       for more	options.

       OPAMDEBUG see options `--debug' and `--debug-level'.

       OPAMDOWNLOADJOBS	sets the maximum number	of simultaneous	downloads.

       OPAMDRYRUN see option `--dry-run`

       OPAMEDITOR sets the editor to use for opam file editing,	overrides
       $EDITOR and $VISUAL

       OPAMERRLOGLEN sets the number of	log lines printed when a sub-process
       fails. 0	to print all.

       OPAMEXTERNALSOLVER see option `--solver'.

       OPAMFAKE	see option `--fake`

       OPAMFETCH specifies how to download files: either `wget', `curl'	or a
       custom command where variables %{url}%, %{out}%,	%{retry}%,
       %{compress}% and	%{checksum}% will be replaced. Overrides the
       'download-command' value	from the main config file.

       OPAMFIXUPCRITERIA same as OPAMUPGRADECRITERIA, but specific to fixup

       OPAMIGNORECONSTRAINTS see install option	`--ignore-constraints-on`

       OPAMIGNOREPINDEPENDS see	option `--ignore-pin-depends`

       OPAMJOBS	sets the maximum number	of parallel workers to run.

       OPAMJSON	log json output	to the given file (use character `%' to	index
       the files)

       OPAMLOCKED see install option `--locked`

       OPAMLOGS	logdir sets log	directory, default is a	temporary directory in

       OPAMMAKECMD set the system make command to use

       OPAMNOAUTOUPGRADE disables automatic internal upgrade of	repositories
       in an earlier format to the current one,	on 'update' or 'init'.

       OPAMKEEPLOGS tells opam to not remove some temporary command logs and
       some backups. This skips	some finalisers	and may	also help to get more
       reliable	backtraces

       OPAMLOCKRETRIES sets the	number of tries	after which opam gives up
       acquiring its lock and fails. <=	0 means	infinite wait.

       OPAMMERGEOUT merge process outputs, stderr on stdout

       OPAMNO answer no	to any question	asked.

       OPAMNOASPCUD Deprecated.

       OPAMNOCHECKSUMS enables option --no-checksums when available.

       OPAMNOSELFUPGRADE see option `--no-self-upgrade'.

       OPAMPINKINDAUTO sets whether version control systems should be detected
       when pinning to a local path. Enabled by	default	since 1.3.0.

       OPAMPRECISETRACKING fine	grain tracking of directories

       OPAMREQUIRECHECKSUMS Enables option `--require-checksums' when
       available (e.g. for `opam install`).

       OPAMRETRES sets the number of tries before failing downloads.

       OPAMROOT	see option `--root'. This is automatically set by `opam	env
       --root=DIR --set-root'.

       OPAMROOTISOK don't complain when	running	as root.

       OPAMSAFE	see option `--safe'

       OPAMSHOW	see option `--show`

       OPAMSKIPUPDATE see option `--skip-updates`

       OPAMSKIPVERSIONCHECKS bypasses some version checks. Unsafe, for
       compatibility testing only.

       OPAMSOLVERTIMEOUT change	the time allowance of the solver. Default is
       60.0, set to 0 for unlimited. Note that all solvers may not support
       this option.

       OPAMSTATUSLINE display a	dynamic	status line showing what's currently
       going on	on the terminal. (one of one of	`always', `never' or `auto')

       OPAMSTATS display stats at the end of command

       OPAMSTRICT fail on inconsistencies (file	reading, switch	import,	etc.)

       OPAMSWITCH see option `--switch'. Automatically set by `opam env
       --switch=SWITCH --set-switch'.

       OPAMUNLOCKBASE see install option `--unlock-base`

       OPAMUPGRADECRITERIA specifies user preferences for dependency solving
       when performing an upgrade. Overrides OPAMCRITERIA in upgrades if both
       are set.	See also option	--criteria

       OPAMUSEINTERNALSOLVER see option	`--use-internal-solver'.

       OPAMUSEOPENSSL force openssl use	for hash computing

       OPAMUTF8	use UTF8 characters in output (one of one of `always', `never'
       or `auto'). By default `auto', which is determined from the locale).

       OPAMUTF8MSGS use	extended UTF8 characters (camels) in opam messages.
       Implies OPAMUTF8. This is set by	default	on OSX only.

       OPAMVALIDATIONHOOK hook if set, uses the	`%{hook%}` command to validate
       an opam repository update

       OPAMVAR_var overrides the contents of the variable var when
       substituting `%{var}%` strings in `opam`	files.

       OPAMVAR_package_var overrides the contents of the variable package:var
       when substituting `%{package:var}%` strings in `opam` files.

       OPAMVERBOSE see option `--verbose'.

       OPAMWORKINGDIR see option `--working-dir`

       OPAMYES see option `--yes'.

       As an exception to the following, the `exec' command returns 127	if the
       command was not found or	couldn't be executed, and the command's	exit
       value otherwise.

       0   Success, or true for	boolean	queries.

       1   False. Returned when	a boolean return value is expected, e.g. when
	   running with	--check, or for	queries	like opam lint.

       2   Bad command-line arguments, or command-line arguments pointing to
	   an invalid context (e.g. file not following the expected format).

       5   Not found. You requested something (package,	version, repository,
	   etc.) that couldn't be found.

       10  Aborted. The	operation required confirmation, which wasn't given.

       15  Could not acquire the locks required	for the	operation.

       20  There is no solution	to the user request. This can be caused	by
	   asking to install two incompatible packages,	for example.

       30  Error in package definition,	or other metadata files. Using
	   --strict raises this	error more often.

       31  Package script error. Some package operations were unsuccessful.
	   This	may be an error	in the packages	or an incompatibility with
	   your	system.	This can be a partial error.

       40  Sync	error. Could not fetch some remotes from the network. This can
	   be a	partial	error.

       50  Configuration error.	Opam or	system configuration doesn't allow
	   operation, and needs	fixing.

       60  Solver failure. The solver failed to	return a sound answer. It can
	   be due to a broken external solver, or an error in solver

       99  Internal error. Something went wrong, likely	due to a bug in	opam

       130 User	interrupt. SIGINT was received,	generally due to the user
	   pressing Ctrl-C.


       Vincent Bernardoff <>
       Raja Boujbel <>
       Roberto Di Cosmo	<>
       Thomas Gazagnaire <>
       Louis Gesbert <>
       Fabrice Le Fessant <>
       Anil Madhavapeddy <>
       Guillem Rieu <>
       Ralf Treinen <>
       Frederic	Tuong <>

       Check bug reports at

Opam 2.0.6							opam-switch(1)


Want to link to this manual page? Use this URL:

home | help