Skip to content

Using Conda

This guide provides general instructions for creating and managing reproducible Conda environments, which are isolated software environments that allow you to manage dependencies, Python versions, and packages without interfering with system-wide installations.

Conda environments are widely used in data science, machine learning, and bioinformatics workflows due to their flexibility and support for cross-platform reproducibility. By maintaining environment configuration files, you can easily recreate setups on different machines or share them with collaborators.

Tip

ScienceCluster users can load Conda tools with:

module load anaconda3
Mamba is also available via module load mamba.

For detailed usage instructions, see the ScienceCluster Conda guide.

ScienceCloud and other users can install Conda tools using micromamba, a lightweight and fast alternative. Installation instructions are available in the Micromamba documentation.

To use micromamba as a drop-in replacement for conda, you can add the following alias:

echo 'alias conda="micromamba"' >> ~/.bashrc
source ~/.bashrc

For more comprehensive information, refer to:

Getting started

Creating an environment

To create a new Conda environment named myenv run:

conda create --name myenv

You’ll be prompted to confirm the creation and package installation.

To create an environment with specific packages from the start (e.g., Python 3.13 and pandas):

conda create --name myenv python=3.13 pandas

Specifying packages during creation helps avoid unnecessary updates and ensures version compatibility from the beginning.

Activating and deactivating

To activate a conda environment

conda activate myenv

Info

Users on shared HPC systems like ScienceCluster may need to use source activate myenv instead.

To deactivate a conda environment:

conda deactivate

Installing packages

To install additional packages to an existing environment

conda install --name myenv <package-name>

If you are already working inside an activated environment you can leave out --name myenv.

To install packages from channels not defined in your ~/.condarc file use the -c flag. For example, the following command will install samtools from the bioconda channel into the myenv conda environment.

conda install --name myenv -c bioconda samtools

Tip

Conda is a convenient way to create a reproducible R environment. To get started, use:

conda create --name renv -c conda-forge r-base
This creates a new environment named renv with the base R installation from the conda-forge channel. You can then install additional R packages using Conda or install.packages() within R.

Managing environments

Listing and removing environments

List environments:

conda env list

Remove an environment:

conda env remove --name myenv --all

Exporting environments

For reproducibility, consider exporting your Conda environment’s configuration. This allows you or others to easily recreate the environment, and the export file can be version-controlled alongside your scientific code in a Git repository.

conda env export  --name myenv > environment.yml

Recreate an environment from a file:

conda env create -f environment.yml

Cleaning the cache

Using the following command, you can free up disk space by removing cached package tarballs, unused packages, and other temporary files:

conda clean -a

This will prompt for confirmation before deleting files. Add -y to skip confirmation:

conda clean --all -y

Neither command will remove any of your installed environments or packages.

If you have installed pip within a Conda environment, you can clean that cache as well:

pip cache purge

Troubleshooting broken environments

There are many possible reasons why a Conda environment might stop working, even if it functioned correctly in the past. While there’s no single solution for all cases, there are two general approaches: either create a new environment from scratch or attempt to repair the existing one.

Start fresh with a new environment

The simplest and most reliable approach is often to create a new environment and start fresh. In some cases, however, this may not fully resolve the issue—for example, if you need to preserve complex dependencies or installed packages that are difficult to reproduce. In such situations, attempting to repair the existing environment might be worthwhile.

Resolving package conflicts from .local

If you’ve accidentally installed packages using pip outside of an activated Conda environment, those packages may be placed in your ~/.local directory. This can cause conflicts with packages in your Conda or other virtual environments.

To check if this is the case:

ls ~/.local
ls ~/.local/lib

If you see directories or files related to Python (e.g., folders named python3.x), it’s a sign that .local contains packages that might be interfering.

Instead of deleting them outright, you can safely isolate them by renaming the directories. This preserves the contents in case they are needed later:

mv ~/.local/lib ~/.local/lib_backup
mv ~/.local/bin ~/.local/bin_backup

Warning

Do not modify ~/.local/share, as it may contain important configuration files used by other applications.

To prevent this issue in the future, always make sure to run:

conda install --name myenv pip

before installing packages with pip inside a Conda environment.

Check version compatibility

To get packages working correctly in a new environment, you may need a specific version of Python or a particular package. Always check the package’s documentation for version requirements.

To create a new environment with a specific Python version:

conda create --name myenv python=3.13

To install a specific version of a package for compatibility with others:

conda install <package_name>=<version_number>

Repair the environment

If recreating the environment is not ideal, you can try to repair the existing one—though success is not guaranteed. Below are some steps that may help resolve issues:

  1. Update all packages
    conda update --all
    
  2. Reinstall a problematic package
    conda remove <package_name>
    conda install <package_name>
    
  3. Check for version compatibility Ensure that package versions are compatible with each other. Reinstall specific versions as needed: Also, check version compatibility of packages, and reinstall specific packages, if needed.
    conda install <package_name>=<version_number>
    

These steps may resolve common issues, but in more complex cases, starting with a fresh environment is often the most reliable solution.