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

FreeBSD Manual Pages


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

       opam-init - Initialize opam state, or set init options.

       opam init [OPTION]... [NAME] [ADDRESS]

       Initialise the opam state, or update opam init options

       The init	command	initialises a local "opam root"	(by default, ~/.opam/)
       that holds opam's data and packages. This is a necessary	step for
       normal operation	of opam. The initial software repositories are
       fetched,	and an initial 'switch'	can also be installed, according to
       the configuration and options. These can	be afterwards configured using
       opam switch and opam repository.

       The initial repository and defaults can be set through a	configuration
       file found at ~/.opamrc or /etc/opamrc.

       Additionally, this command allows one to	customise some aspects of
       opam's shell integration, when run initially (avoiding the interactive
       dialog),	but also at any	later time.

	   Address of the initial package repository, when creating a new opam

       NAME (absent=default)
	   Name	of the initial repository, when	creating a new opam root.

       -a, --auto-setup
	   Automatically do a full setup, including adding a line to your
	   shell init files.

	   Initialise the opam state, but don't	setup any compiler switch yet.

	   Skip	checks on required or recommended tools, and assume everything
	   is fine

       -c PACKAGE, --compiler=PACKAGE
	   Set the compiler to install (when creating an initial switch)

	   Use the given init config file. If repeated,	latest has the highest
	   priority (i.e. each field gets its value from where it was defined
	   last). Specifying a URL pointing to a config	file instead is

	   Disable shell completion in opam init scripts.

	   Use a default configuration with sandboxing disabled	(note that
	   this	may be overridden by `opamrc' if --no-opamrc is	not specified
	   or --config is used). Use this at your own risk, without sandboxing
	   it is possible for a	broken package script to delete	all your

	   Disable registration	of a shell hook	in opam	init scripts.

	   Name	of the configuration file to update instead of ~/.profile or
	   ~/.zshrc based on shell detection.

	   Setup shell completion in opam init scripts,	for supported shells.

	   Setup opam init scripts to register a shell hook that will
	   automatically keep the shell	environment up-to-date at every

       -i, --interactive
	   Run the setup interactively (this is	the default for	an initial
	   run,	or when	no more	specific options are specified)

       -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.

       -k KIND,	--kind=KIND
	   Specify the kind of the repository to be used (one of `http',
	   `local', `git', `darcs' or `hg').

       -n, --no-setup
	   Do not update the user shell	configuration to setup opam. Also
	   implies --disable-shell-hook, unless	--interactive or specified

	   Don't read `/etc/opamrc' or `~/.opamrc': use	the default settings
	   and the files specified through --config only

	   Re-run the initial checks and setup,	according to opamrc, even if
	   this	is not a new opam root

	   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.

	   Automatically setup the user	shell configuration for	opam, e.g.
	   adding a line to the	`~/.profile' file.

	   Print the built-in default configuration to stdout and exit

       Any field from the built-in initial configuration can be	overridden
       through ~/.opamrc, /etc/opamrc, or a file supplied with --config. The
       default configuration for this version of opam can be obtained using

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


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

home | help