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

FreeBSD Manual Pages


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

       opam-config - Display configuration options for packages.

       opam config [OPTION]... [COMMAND] [ARG]...

       This command uses opam state to output information on how to use
       installed libraries, update the PATH, and substitute variables used in
       opam packages.

       Apart from opam config env, most	of these commands are used by opam
       internally, and are of limited interest for the casual user.

       env Returns the bindings	for the	environment variables set in the
	   current switch, e.g.	PATH, in a format intended to be evaluated by
	   a shell. With -v, add comments documenting the reason or package of
	   origin for each binding. This is most usefully used as eval $(opam
	   config env) to have further shell commands be evaluated in the
	   proper opam context.	Can also be accessed through opam env.

	   Reverts environment changes made by opam, e.g. eval $(opam config
	   revert-env) undoes what eval	$(opam config env) did,	as much	as

       exec [--] COMMAND [ARG]...
	   Execute COMMAND with	the correct environment	variables. This
	   command can be used to cross-compile	between	switches using opam
	   config exec --switch=SWITCH -- COMMAND ARG1 ... ARGn. Opam
	   expansion takes place in command and	args. If no switch is present
	   on the command line or in the OPAMSWITCH environment	variable,
	   OPAMSWITCH is not set in COMMAND's environment. Can also be
	   accessed through opam exec.

       var VAR
	   Return the value associated with variable VAR. Package variables
	   can be accessed with	the syntax pkg:var. Can	also be	accessed
	   through opam	var

       list [PACKAGE]...
	   Without argument, prints a documented list of all available
	   variables. With PACKAGE, lists all the variables available for
	   these packages. Use - to include global configuration variables for
	   this	switch.

       set VAR VALUE
	   Set the given opam variable for the current switch. Warning:
	   changing a configured path will not move any	files! This command
	   does	not perform any	variable expansion.

       unset VAR
	   Unset the given opam	variable for the current switch. Warning:
	   unsetting built-in configuration variables can cause	problems!

       set-global VAR VALUE
	   Set the given variable globally in the opam root, to	be visible in
	   all switches

       unset-global VAR
	   Unset the given global variable

       expand STRING
	   Expand variable interpolations in the given string

       subst FILE...
	   Substitute variables	in the given files. The	strings	%{var}%	are
	   replaced by the value of variable var (see var).

	   Prints a summary of your setup, useful for bug-reports.

       cudf-universe [FILE]
	   Outputs the current available package universe in CUDF format.

       pef-universe [FILE]
	   Outputs the current package universe	in PEF format.

	   When	updating the PATH variable, replace any	pre-existing opam path
	   in-place rather than	putting	the new	path in	front. This means
	   programs installed in opam that were	shadowed will remain so	after
	   opam	env

	   With	the env	and exec subcommands, also sets	the OPAMROOT variable,
	   making sure further calls to	opam will use the same root.

	   With	the env	and exec subcommands, also sets	the OPAMSWITCH
	   variable, making sure further calls to opam will use	the same
	   switch as this one.

	   Print environment as	an s-expression	rather than in shell format

	   Sets	the configuration mode for opam	environment appropriate	for
	   SHELL. One of one of	`bash',	`sh', `csh', `zsh' or `fish'. Guessed
	   from	the parent processes and the $SHELL variable by	default.

       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-config(1)


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

home | help