If you are new to conda, I recommend starting at the documentation, and watching my presentation from SciPy 2014.
In this post, I will assume that you are already familiar with conda and its basic usage, both for installing and building packages. I will look at a few advanced features or tips that may not be well known, even among advanced users of conda. These features will help you with feature discovery, customization, and allow you to manage your packages and environments in more advanced ways.
The best way to learn about the features of conda is to run a subcommand, followed by
--help. For example, to see everything that the install command is capable of, we can run:
$conda install –help
usage: conda install [-h] [–revision REVISION] [–yes] [–dry-run] [-f]
[–file FILE] [–unknown] [–no-deps] [-m]
[–use-index-cache] [–use-local] [–no-pin] [-c CHANNEL]
[–override-channels] [-n NAME | -p PATH] [-q]
[package_spec [package_spec …]]
Install a list of packages into a specified conda environment.
The arguments may be packages specifications (e.g. bitarray=0.8),
or explicit conda packages filesnames (e.g. lxml-3.2.0-py27_0.tar.bz2) which
must exist on the local filesystem. The two types of arguments cannot be
mixed and the latter implies the –force and –no-deps options.
package_spec package versions to install into conda environment
-h, –help show this help message and exit
–revision REVISION revert to the specified REVISION
–yes do not ask for confirmation
–dry-run only display what would have been done
-f, –force force install (even when package already installed),
–file FILE read package versions from FILE
–unknown use index metadata from the local package cache (which
are from unknown channels)
–no-deps do not install dependencies
-m, –mkdir create prefix directory if necessary
–use-index-cache use cache of channel index files
–use-local use locally built packages
–no-pin don’t use pinned packages
-c CHANNEL, –channel CHANNEL
additional channel to search for packages. These are
URLs searched in the order they are given (including
file:// for local directories). Then, the defaults or
channels from .condarc are searched (unless
–override-channels is given). You can use ‘defaults’
to get the default packages for conda, and ‘system’ to
get the system packages, which also takes .condarc
into account. You can also use any name and the
.condarc channel_alias value will be prepended. The
default channel_alias is http://conda.anaconda.org/
–override-channels Do not search default or .condarc channels. Requires
-n NAME, –name NAME name of environment (in
-p PATH, –prefix PATH
full path to environment prefix (default:
-q, –quiet do not display progress bar
–alt-hint Use an alternate algorithm to generate an
conda install -n myenv scipy
To see all possible
conda commands, run
Conda supports several configuration options. The easiest way to modify these options is to use the
conda config command. This command modifies your
.condarc file, which is in your user directory by default. The
.condarc file uses YAML syntax.
There are several useful configuration values that conda supports. The most common configuration option is
channels, which lets you install other people’s packages from Anaconda.org, but other useful flags exist as well, allowing you to change conda’s behavior when it creates new environments, or how it interacts at the command line, for example.
There are two kinds of keys in the conda configuration: list keys and boolean keys.
List keys take a list of values. For example,
channels is a list of channels from which conda will search for packages. To add something to a list key, use
conda config --add.
conda config --add channels asmeurer will add my Binstar channel. Other useful list keys are
channels: List of channels that conda will search for packages.
defaultsis a special channel that refers to the default Continuum channels that come with conda. A channel can be a url, or a Binstar username.
create_default_packages: A list of packages that are included in every new environment by default.
envs_dirs: A list of directories that conda will use to create environments and keep its package cache.
Boolean keys are either true or false. YAML allows several ways to spell true and false.
TRUE are all valid ways to spell “true”, and
FALSE, are all valid ways to spell “false”.
Boolean keys are set using
conda config --set. Some useful boolean keys are
always_yes: Prevent conda from showing
[Y/n]confirmation dialogs. If you enable this, you can pass the
--dry-runto the various commands like
conda cleanto see what they would do without actually doing it.
binstar_upload: If true, conda build will always upload to Binstar when it is finished building successfully.
changeps1: If true, the default, the
activatescript will add the name of the environment to the command prompt. If you don’t like this, or want to do it manually using the
CONDA_DEFAULT_ENVenvironment variable, you can set this to false.
There are other configuration values as well, some of which cannot currently be set using
conda config. See the conda configuration documentation for a full list of possible values.
conda update --all
Conda uses a SAT solver coupled with a system of pseudo-boolean constraints which are reduced to SAT conditions to solve package dependencies. Whenever conda installs something, it tries to find the combination of packages that has the latest possible versions that work together.
Updating all packages is therefore just a matter of trying to install every package, and letting the SAT solver get the latest versions available.
conda update --all is an easy way to do this. For example, if you have Python 2.7.4, NumPy 1.8.0, and SciPy 0.14.0 installed,
conda update --all is the same as
conda install "python>=2.7.4,<3" "numpy>=1.8.0" "scipy>=0.14.0" (except also including several dependencies of Python such as readline and OpenSSL). Note that
conda update --all will not “update” you from Python 2 to Python 3.
Note that sometimes your environment may be in an inconsistent state, and it will be impossible for conda to solve the package specification problem. In this case, it will say “Unsatisfiable package specifications” and start generating a hint. You can cancel the hint generation using Control-C, or wait for it to finish (it may take a while, especially with
conda update --all). A common problem is that if you want to update package versions past the versions specified in the
anaconda metapackage, you will need to remove it with
conda remove anaconda. (This will only remove the metapackage, which doesn’t contain any code.)
anaconda metapackage is designed for people who want to keep a stable set of packages, which have been tested together. It is updated every few months. If you want to do this, you should keep
anaconda installed and use
conda update anaconda to update things. If you want to update packages individually to the latest versions as they come out, you should
conda remove anaconda and use
conda update --all to keep packages up-to-date.
conda list --export and
conda create --file
Conda makes it easy to reproduce an environment exactly.
conda list --export will export all the packages you have installed exactly, down to the version and build string. You can then save this to a file, and install the same packages again with
conda install --file or
conda create --file. For example:
$ conda list –export
# This file may be used to create an environment using:
# $ conda create –name
$ conda list –export > exported_packages.txt
$ conda create -n newenv –file exported_packages.txt
Fetching package metadata: ………….
Solving package specifications:
Package plan for installation in environment /Users/aaronmeurer/anaconda/envs/newenv:
The following NEW packages will be INSTALLED:
openssl: 1.0.1h-0 defaults
python: 3.4.1-0 defaults
readline: 6.2-2 defaults
sqlite: 22.214.171.124-0 asmeurer
sympy: 0.7.5-py34_0 asmeurer
tk: 8.5.15-0 defaults
zlib: 1.2.7-1 defaults
Linking packages …
[ COMPLETE ] |#######################################################| 100%
# To activate this environment, use:
# $ source activate newenv
# To deactivate this environment, use:
# $ source deactivate
After being used for a while, conda can accumulate a lot of disk space, because it doesn’t remove old unused packages.
To remove unused packages, run
conda clean -p. This command checks which packages in the pkgs cache are not hard linked anywhere and removes them. Note that if you install packages via symlinking, e.g., to or from a separate filesystem, you should not use this command, as it will not be able to detect that.
Conda also keeps the tarballs for all the packages it downloads. These are only kept around for caching purposes. They can be deleted. To delete all the package tarballs, run
conda clean -t.
By default, conda will always try to install the latest version of a package in an environment. However, sometimes you may want to keep a package as an older version, even if you install later things which may depend on it (conda by default will update all dependencies of any package you install).
For example, suppose you have SciPy 0.13.3 installed in an environment, and you don’t want to accidentally update to 0.14.0 (the latest version at the time of this writing), even if you install other packages that depend on SciPy, like Pandas.
To do this, write a file called
pinned to the
conda-meta directory of the environment. For instance, if you have an environment called
scipy-0.13, you could do
$ echo "scipy 0.13.3" > ~/anaconda/envs/scipy-0.13/conda-meta/pinned
Each line in the pinned file should be a conda match specification. This allows more general things, like specifying
scipy <0.14. Lines that start with
# are ignored.
The way it works is that each time conda installs something in that environment, the lines from the pinned file are added to the list of what conda sends to the SAT solver, so that they are prevented from ever changing.
To ignore the pinned file, use
conda install --no-pin.
This concludes part 1 of the Advanced Features of Conda blog series. In part 2, we will look at some more advanced features, including tricks to make it easier to build your own conda packages using conda build and to be more powerful at managing your conda environments.