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
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
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:
- Update all packages
conda update --all
- Reinstall a problematic package
conda remove <package_name> conda install <package_name>
- 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.