Docs - Conda.io-Managing Environments
Docs - Conda.io-Managing Environments
docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html
Updating an environment
Cloning an environment
Activating an environment
Deactivating an environment
Sharing an environment
Restoring an environment
Removing an environment
With conda, you can create, export, list, remove, and update environments that have
different versions of Python and/or packages installed in them. Switching or moving
between environments is called activating the environment. You can also share an
environment file.
Note
There are many options available for the commands described on this page. For details,
see Command reference.
Note
1/16
conda activate and conda deactivate only work on conda 4.6 and later versions. For
conda versions prior to 4.6, run:
Tip
By default, environments are installed into the envs directory in your conda directory.
See Specifying a location for an environment or run conda create --help for information
on specifying a different path.
1. To create an environment:
Note
proceed ([y]/n)?
This creates the myenv environment in /envs/ . This environment uses the same version
of Python that you are currently using because you did not specify a version.
OR:
OR:
2/16
6. To create an environment with a specific version of Python and multiple packages:
Tip
Install all the programs that you want in this environment at the same time. Installing 1
program at a time can lead to dependency conflicts.
To automatically install pip or another program every time a new environment is created,
add the default programs to the create_default_packages section of your .condarc
configuration file. The default packages are installed every time you create a new
environment. If you do not want the default packages installed in a particular
environment, use the --no-default-packages flag:
Tip
You can add much more to the conda create command. For details, run conda create --
help .
The first line of the yml file sets the new environment's name. For details see
Creating an environment file manually.
You can control where a conda environment lives by providing a path to a target
directory when creating the environment. For example, the following command will
create a new environment in a subdirectory of the current working directory called
envs :
You then activate an environment created with a prefix using the same command used
to activate environments created by name:
3/16
Specifying a path to a subdirectory of your project directory when creating an
environment has the following benefits:
It makes it easy to tell if your project uses an isolated environment by including the
environment as a subdirectory.
There are a few things to be aware of when placing conda environments outside of the
default envs folder.
1. Conda can no longer find your environment with the --name flag. You’ll generally
need to pass the --prefix flag along with the environment’s full path to find the
environment.
2. Specifying an install path when creating your conda environments makes it so that
your command prompt is now prefixed with the active environment’s absolute
path rather than the environment’s name.
After activating an environment using its prefix, your prompt will look similar to the
following:
(/absolute/path/to/envs) $
(/Users/USER_NAME/research/data-science/PROJECT_NAME/envs) $
To remove this long prefix in your shell prompt, modify the env_prompt setting in your
.condarc file:
This will edit your .condarc file if you already have one or create a .condarc file if you
do not.
Now your command prompt will display the active environment’s generic name, which is
the name of the environment's root folder:
$ cd project-directory
$ conda activate ./env
(env) project-directory $
4/16
Updating an environment
You may need to update your environment for a variety of reasons. For example, it may
be the case that:
one of your core dependencies just released a new version (dependency version
number update).
you need an additional package for data analysis (add a new dependency).
you have found a better package and no longer need the older package (add new
dependency and remove old dependency).
If any of these occur, all you need to do is update the contents of your environment.yml
file accordingly and then run the following command:
Note
The --prune option causes conda to remove any dependencies that are no longer
required from the environment.
Cloning an environment
Use the terminal or an Anaconda Prompt for the following steps:
Note
Replace myclone with the name of the new environment. Replace myenv with the
name of the existing environment that you want to copy.
In the environments list that displays, you should see both the source environment and
the new copy.
2. To create this spec list as a file in the current working directory, run:
Note
You can use spec-file.txt as the filename or replace it with a filename of your
choice.
An explicit spec file is not usually cross platform, and therefore has a comment at
the top such as # platform: osx-64 showing the platform where it was created.
This platform is the one where this spec file is known to work. On other platforms,
the packages specified might not be available or dependencies might be missing for
some of the key packages already in the spec.
To use the spec file to create an identical environment on the same machine or
another machine:
To use the spec file to install its listed packages into an existing environment:
Conda does not check architecture or dependencies when installing from a spec
file. To ensure that the packages work correctly, make sure that the file was created
from a working environment, and use it on the same architecture, operating
system and platform, such as linux-64 or osx-64.
Activating an environment
Activating environments is essential to making the software in the environments work
6/16
well. Activation entails two primary functions: adding entries to PATH for the
environment, and running any activation scripts that the environment may contain.
These activation scripts are how packages can set arbitrary environment variables that
may be necessary for their operation.
When installing Anaconda, you have the option to “Add Anaconda to my PATH
environment variable.” This is not recommended because the add to PATH option
appends Anaconda to PATH. When the installer appends to PATH, it does not call the
activation scripts.
On Windows, PATH is composed of two parts, the system PATH and the user PATH. The
system PATH always comes first. When you install Anaconda for Just Me, we add it to the
user PATH. When you install for All Users, we add it to the system PATH. In the former
case, you can end up with system PATH values taking precedence over our entries. In the
latter case, you do not. We do not recommend multi-user installs.
Activation prepends to PATH. This only takes effect when you have the environment
active so it is local to a terminal session, not global.
Note
Conda prepends the path name myenv onto your system command.
You may receive a warning message if you have not activated your environment:
Warning:
This Python interpreter is in a conda environment, but the environment has
not been activated. Libraries may fail to load. To activate this environment
please see https://conda.io/activation.
If you receive this warning, you need to activate your environment. To do so on Windows,
run: c:\Anaconda3\Scripts\activate base in Anaconda Prompt.
Windows is extremely sensitive to proper activation. This is because the Windows library
loader does not support the concept of libraries and executables that know where to
search for their dependencies (RPATH). Instead, Windows relies on a dynamic-link library
search order.
If environments are not active, libraries won't be found and there will be lots of errors.
HTTP or SSL errors are common errors when the Python in a child environment can't find
the necessary OpenSSL library.
Conda itself includes some special workarounds to add its necessary PATH entries. This
makes it so that it can be called without activation or with any child environment active.
In general, calling any executable in an environment without first activating that
7/16
environment will likely not work. For the ability to run executables in activated
environments, you may be interested in the conda run command.
Conda init
Earlier versions of conda introduced scripts to make activation behavior uniform across
operating systems. Conda 4.4 allowed conda activate myenv . Conda 4.6 added extensive
initialization support so that conda works more quickly and less disruptively on a wide
variety of shells (bash, zsh, csh, fish, xonsh, and more). Now these shells can use the
conda activate command. Removing the need to modify PATH makes conda less
disruptive to other software on your system. For more information, read the output from
conda init --help .
One setting may be useful to you when using conda init is:
auto_activate_base: bool
This setting controls whether or not conda activates your base environment when it first
starts up. You'll have the conda command available either way, but without activating
the environment, none of the other programs in the environment will be available until
the environment is activated with conda activate base . People sometimes choose this
setting to speed up the time their shell takes to start up or to keep conda-installed
software from automatically hiding their other software.
Nested activation
By default, conda activate will deactivate the current environment before activating the
new environment and reactivate it when deactivating the new environment. Sometimes
you may want to leave the current environment PATH entries in place so that you can
continue to easily access command line programs from the first environment. This is
most commonly encountered when common command-line utilities are installed in the
base environment. To retain the current environment in the PATH, you can activate the
new environment using:
If you wish to always stack when going from the outermost environment, which is
typically the base environment, you can set the auto_stack configuration option:
You may specify a larger number for a deeper level of automatic stacking, but this is not
recommended since deeper levels of stacking are more likely to lead to confusion.
Warning
If you choose not to activate your environment, then loading and setting environment
variables to activate scripts will not happen. We only support activation.
Deactivating an environment
To deactivate an environment, type: conda deactivate
Conda removes the path name for the currently active environment from your system
command.
Note
To simply return to the base environment, it's better to call conda activate with no
environment specified, rather than to try to deactivate. If you run conda deactivate from
your base environment, you may lose the ability to run conda at all. Don't worry, that's
local to this shell - you can start a new one. However, if the environment was activated
using --stack (or was automatically stacked) then it is better to use conda deactivate .
By default, the active environment---the one you are currently using---is shown in
parentheses () or brackets [] at the beginning of your command prompt:
(myenv) $
In the environments list that displays, your current environment is highlighted with an
asterisk (*).
By default, the command prompt is set to show the name of the active environment. To
disable this option:
OR
conda environments:
myenv /home/username/miniconda/envs/myenv
snowflakes /home/username/miniconda/envs/snowflakes
bunnies /home/username/miniconda/envs/bunnies
conda list
Issues may arise when using pip and conda together. When combining conda and pip, it
is best to use an isolated conda environment. Only after conda has been used to install
as many packages as possible should pip be used to install any remaining software. If
10/16
modifications are needed to the environment, it is best to create a new environment
rather than running conda after pip. When appropriate, conda and pip requirements
should be stored in text files.
Do not use pip with the --user argument, avoid all “users” installs
Conda env will export or create environments based on a file with conda and pip
requirements
Suppose you want an environment "analytics" to store both a secret key needed to log in
to a server and a path to a configuration file. The sections below explain how to write a
script named env_vars to do this on Windows and macOS or Linux.
This type of script file can be part of a conda package, in which case these environment
variables become active when an environment containing that package is activated.
You can name these scripts anything you like. However, multiple packages may create
script files, so be sure to use descriptive names that are not used by other packages. One
popular option is to give the script a name in the form packagename-scriptname.sh , or
on Windows, packagename-scriptname.bat .
11/16
Windows
1. Locate the directory for the conda environment in your Anaconda Prompt by
running in the command shell %CONDA_PREFIX% .
cd %CONDA_PREFIX%
mkdir .\etc\conda\activate.d
mkdir .\etc\conda\deactivate.d
type NUL > .\etc\conda\activate.d\env_vars.bat
type NUL > .\etc\conda\deactivate.d\env_vars.bat
set MY_KEY='secret-key-value'
set MY_FILE=C:\path\to\my\file
set MY_KEY=
set MY_FILE=
When you run conda activate analytics , the environment variables MY_KEY and MY_FILE
are set to the values you wrote into the file. When you run conda deactivate , those
variables are erased.
cd $CONDA_PREFIX
mkdir -p ./etc/conda/activate.d
mkdir -p ./etc/conda/deactivate.d
touch ./etc/conda/activate.d/env_vars.sh
touch ./etc/conda/deactivate.d/env_vars.sh
#!/bin/sh
export MY_KEY='secret-key-value'
export MY_FILE=/path/to/my/file/
12/16
4. Edit ./etc/conda/deactivate.d/env_vars.sh as follows:
#!/bin/sh
unset MY_KEY
unset MY_FILE
When you run conda activate analytics , the environment variables MY_KEY and MY_FILE
are set to the values you wrote into the file. When you run conda deactivate , those
variables are erased.
Sharing an environment
You may want to share your environment with someone else---for example, so they can
re-create a test that you have done. To allow them to quickly reproduce your
environment, with all of its packages and versions, give them a copy of your
environment.yml file .
Note
Note
This file handles both the environment's pip packages and conda packages.
For example, if you create an environment and install Python and a package:
13/16
conda install python=3.7 codecov
This will download and install numerous additional packages to solve for dependencies.
This will introduce packages that may not be compatible across platforms.
If you use conda env export , it will export all of those packages. However, if you use
conda env export --from-history , it will only export those you specifically chose:
Note
name: stats
dependencies:
- numpy
- pandas
name: stats2
channels:
- javascript
dependencies:
- python=3.6 # or 2.7
- bokeh=0.9.2
- numpy=1.9.*
- nodejs=0.10.*
- flask
- pip:
- Flask-Testing
Note
Note the use of the wildcard * when defining the patch version number. Defining the
version number by fixing the major and minor version numbers while allowing the patch
14/16
version number to vary allows us to use our environment file to update our environment
to get any bug fixes whilst still maintaining consistency of software environment.
You can exclude the default channels by adding nodefaults to the channels list.
channels:
- javascript
- nodefaults
For details on creating an environment from this environment.yml file, see Creating an
environment from an environment.yml file.
Restoring an environment
Conda keeps a history of all the changes made to your environment, so you can easily
"roll back" to a previous version. To list the history of each change to the current
environment: conda list --revisions
Note
Example: If you want to restore your environment to revision 8, run conda install --rev 8 .
Removing an environment
To remove an environment, in your terminal window or an Anaconda Prompt, run:
To verify that the environment was removed, in your terminal window or an Anaconda
Prompt, run:
The environments list that displays should not show the removed environment.
15/16
16/16