Overview Conda environments are isolated workspaces that contain specific collections of packages. They allow you to maintain different versions of packages for different projects without conflicts.
The base environment is your default conda environment. It’s recommended to create separate environments for different projects rather than installing everything in base.
Creating Environments Basic Creation Use conda create to create a new environment:
# Create environment with a name conda create -n myenv # Create with specific Python version conda create -n myenv python= 3.11 # Create with multiple packages conda create -n myenv numpy pandas matplotlib
You must provide either -n NAME or -p PREFIX when creating an environment (unless using --dry-run or --download-only).
Advanced Options
Clone an Existing Environment
# Clone an environment conda create -n env2 --clone env1 # Clone from specific path conda create -n newenv --clone /path/to/existing/env
When using --clone, you cannot specify additional packages or use --file.
Create from Environment File
# Create from environment.yml conda create -n myenv --file environment.yml # Create from requirements.txt conda create -n myenv --file requirements.txt
Reserved Environment Names Certain environment names are reserved and cannot be used:
ROOT_ENV_NAME = "base" RESERVED_ENV_NAMES = ( "base" , "root" , )
Attempting to create an environment with a reserved name will result in an error.
Activating and Deactivating Activation Activating an environment modifies your shell’s PATH and environment variables:
Activate by Name
Activate by Path
# Activate named environment conda activate myenv # Activate base environment conda activate base
Deactivation # Deactivate current environment conda deactivate
Deactivating returns you to the base environment or your system’s default Python.
Supported Shells Conda supports activation in multiple shells:
COMPATIBLE_SHELLS = ( "bash" , "fish" , "tcsh" , "xonsh" , "zsh" , "powershell" , )
COMPATIBLE_SHELLS = ( "bash" , "cmd.exe" , "fish" , "tcsh" , "xonsh" , "zsh" , "powershell" , )
Listing Environments List All Environments # List all conda environments conda env list # Alternative command conda info --envs
Output example:
# conda environments: # base * /opt/anaconda3 myenv /opt/anaconda3/envs/myenv project1 /home/user/projects/ml/.conda
The asterisk (*) indicates the currently active environment.
List Packages in Environment # List all packages in active environment conda list # List packages in specific environment conda list -n myenv # List packages in environment at path conda list -p /path/to/myenv
Removing Environments Remove Entire Environment Remove by Name
Remove by Path
# Remove environment by name conda env remove -n myenv # Alternative: use conda remove conda remove -n myenv --all
Removing an environment deletes all files in the environment directory. This action cannot be undone.
Protected Packages in Base Certain packages in the base environment cannot be removed:
ROOT_NO_RM = ( "python" , "pycosat" , "ruamel.yaml" , "conda" , "openssl" , "requests" , )
Environment Files The environment.yml file is the standard way to define conda environments:
Basic environment.yml
With pip dependencies
With environment variables
name : myproject channels : - conda-forge - defaults dependencies : - python=3.11 - numpy=1.24 - pandas>=2.0 - matplotlib
Creating from File # Create environment from file conda env create -f environment.yml # Create with different name conda env create -f environment.yml -n custom_name # Create at specific path conda env create -f environment.yml -p /path/to/env
Exporting Environments Export to YAML
Export to requirements.txt
# Export current environment conda env export > environment.yml # Export specific environment conda env export -n myenv > environment.yml # Export without builds (more portable) conda env export --no-builds > environment.yml # Export from history (only explicitly installed) conda env export --from-history > environment.yml
Use --from-history to create more portable environment files that only include packages you explicitly installed, not their dependencies.
Explicit Specification Files For exact environment reproduction, use explicit specifications:
# Export explicit spec conda list --explicit > spec-file.txt # Create from explicit spec conda create -n myenv --file spec-file.txt
Explicit files contain full URLs to packages and are prefixed with:
EXPLICIT_MARKER = "@EXPLICIT"
Explicit specifications are platform-specific and guarantee exact reproduction of an environment, including build numbers.
Every conda environment stores metadata in the conda-meta/ directory:
History File # View environment history cat $CONDA_PREFIX /conda-meta/history
The history file tracks:
Installation and update commands
Package changes over time
Timestamps of operations
PREFIX_MAGIC_FILE = join( "conda-meta" , "history" )
PREFIX_STATE_FILE = join( "conda-meta" , "state" ) PREFIX_PINNED_FILE = join( "conda-meta" , "pinned" ) PREFIX_FROZEN_FILE = join( "conda-meta" , "frozen" ) PREFIX_CREATION_TIMESTAMP_FILE = join( "conda-meta" , "created_at" )
Pinned Packages Pin packages to prevent them from being updated:
# Add pinned packages echo "numpy ==1.24.*" >> $CONDA_PREFIX /conda-meta/pinned echo "python 3.11.*" >> $CONDA_PREFIX /conda-meta/pinned
Pinned packages remain at their specified versions unless explicitly updated.
Environment Variables Setting Environment Variables Create activation scripts in etc/conda/env_vars.d/:
# Create directory mkdir -p $CONDA_PREFIX /etc/conda/env_vars.d # Create activation script cat > $CONDA_PREFIX /etc/conda/env_vars.d/env_vars.sh << EOF export MY_VAR="value" export PATH="/custom/path: \$ PATH" EOF
Unsetting Variables To unset a variable when activating:
CONDA_ENV_VARS_UNSET_VAR = "***unset***"
echo "export MY_VAR= $CONDA_ENV_VARS_UNSET_VAR " >> $CONDA_PREFIX /etc/conda/env_vars.d/env_vars.sh
The PATH variable is reserved and managed by conda. Custom PATH modifications should be done carefully.
Best Practices
Use Separate Environments for Projects
Keep each project in its own environment to avoid dependency conflicts: conda create -n project1 python= 3.11 conda create -n project2 python= 3.9
Use environment.yml for Team Collaboration
Share environment files with your team: # Export conda env export --from-history > environment.yml # Others can recreate conda env create -f environment.yml
Regularly Update Environments
Keep your environments up to date: conda update -n myenv --all
Clean Up Unused Environments
Remove environments you no longer need: conda env remove -n old_project conda clean --all
Troubleshooting
Environment Already Exists
When creating an environment that already exists, conda will prompt you to remove it first: # Remove and recreate conda env remove -n myenv conda create -n myenv python= 3.11
Cannot Activate Environment
Ensure conda is properly initialized for your shell: conda init bash # or zsh, fish, etc.
Then restart your shell.
Verify the environment exists: Check both by name and by path. Next Steps
Package Management Learn how to install and manage packages in environments
Channel Management Configure package channels for your environments