Manage Scientific Software with 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.

module load miniforge3

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

For more comprehensive information, refer to:

• 📘 Official Conda User Guide
• 🛠️ Conda Command Reference

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.14 and pandas):

conda create --name myenv python=3.14 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

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

conda create --name renv -c conda-forge r-base

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

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.