Conda (Miniforge)

Conda is a package manager that can be used to install additional programs and libraries into custom environments. It is included with, but can be installed independently of, the Anaconda Python distribution.

Anaconda or Conda

Anaconda includes the Conda package manager along with many other packages.

For most cases, SENS recommends using Conda instead of Anaconda. An edition of Conda known as Miniforge uses free and openly-licensed packages from the conda-forge project by default. Conda also uses significantly less space and installs much faster than Anaconda.

If you want to get started with many common packages, Anaconda may be used. However, there are conditions that must be fulfilled for usage at UB. To review these conditions, refer to our Anaconda page.

Editions

Conda is published in several editions outside of Anaconda.

Miniforge is an edition of Conda that only uses free and openly-licensed packages from the conda-forge project by default. For users without an Anaconda license, SENS recommends using Miniforge to avoid accidental violations of the Anaconda terms of service.

Miniconda is Anaconda without most default packages, but it is subject to the same terms of service as Anaconda. As such, SENS does not support installing Miniconda - Miniforge or Anaconda may be used instead.

Installation

For UB-owned Windows devices maintained by SENS, Miniforge is available in Software Center.

For UB-owned macOS devices maintained by SENS, Miniforge is available in Self Service.

For UB-owned Linux devices maintained by SENS, Miniforge is available in networked storage. It may be brought into an interactive shell session by running the following command.


use conda

For personally-owned devices, Miniforge can be downloaded from Miniforge's GitHub repo. Instructions are provided in the project's README document.

Usage

Conda is a command-line (CLI) tool. You will need to use one of the following to interact with it.

  • Windows
    • Windows Terminal
    • PowerShell
    • Command Prompt
  • macOS
    • Terminal
    • iTerm
  • Linux Desktop
    • GNOME Terminal
    • MATE Terminal

If you are using Conda on a Linux server, you will need to connect to it using an SSH client such as OpenSSH or PuTTY.

About Conda Environments

Conda can install software into one or more directories of your choosing. These directories are referred to as Conda environments. If an environment is located within a directory you own, such as your Documents folder, software can be installed in this environment without needing administrative privileges.

Software is distributed as Conda packages with names like python or numpy. The servers packages come from are referred to as Conda channels. Conda can install a wide range of software from its default channels, but some packages may require that an additional channel be specified. Use caution when downloading software from a third-party channel.

Unlike some other package systems, Conda stores packages separately from the environments they are added to. This allows Conda to reuse packages across multiple environments without making full copies of each package. The location Conda installs packages in can be set on a per-user or a per-environment basis.

There are some additional details that are important to be aware of:

  • Once created, a Conda environment should not be moved.
    • If an environment needs to be relocated, it should be recreated in its new location.
  • Multiple Conda environments can be set up for different projects.
    • This is especially useful if different projects require different versions of packages (e.g. Python 3.11 or Python 3.12).
  • Conda environments should not be shared between users.
    • Conda can set file permissions in unexpected ways, leading to errors when multiple people attempt to modify an environment.
    • To ensure multiple people have access to identical environments, a list of packages may be exported from one environment and imported into others.

Creating a New Environment

To create a new Conda environment, initialize a directory using the following command, where $env_path is the environment's directory.


conda create -p "$env_path"

To use a Conda environment, it must be activated in the command-line session. This can be done using a command like the following.


conda activate "$env_path"

Before installing any packages, you may wish to change where the environment's packages are stored. Conda packages are stored in your profile directory or home directory by default. Since Conda can download gigabytes of packages, this can fill up a disk or a quota quickly.

To set the package location on a per-environment basis, run commands like the following, where $pkgs_path is the location conda packages are stored.


conda config --env --remove-key pkgs_dirs
conda config --env --add pkgs_dirs "$pkgs_path"

Now that the environment has been prepared and activated, packages may be installed in it. Packages can be given to Conda with a version specification (e.g. python=3.10, scipy>=1.7,<2) or without (e.g. numpy). Conda will try to obtain the latest versions of all requested packages that meet the specifications and are compatible with one another.

The installation command can accept more than one package at a time, separated by spaces. If multiple packages are to be installed, it is best to specify them using a single install command, as this allows Conda to figure out compatibility issues upfront.

For example, the following install command will install the newest version of Python 3.10, the latest compatible version of NumPy, and the latest compatible version of SciPy greater than or equal to 1.7 but less than 2.0.


conda install "python=3.10" "numpy" "scipy>=1.7,<2"

Exporting and Importing Environments

Environment definitions can be saved to YAML files using an export mechanism, and an environment definition file can be used to create the same environment in a different location or on a different machine.

Exporting Environments

An environment's list of packages can be exported using two different levels of specificity: requirements-only or all-packages. In a requirements-only export, only the packages that were explicitly requested for installation will be saved to an export file. In an all-packages export, the name and version of every package installed in an environment is exported, including dependencies of the requested packages.

For portability between systems, the requirements-only definition generally works best, as different systems may need to pull in different dependencies to meet the requirements. An all-packages definition works best when trying to exactly replicate one environment in a different location. When archiving a project, it may be best to perform both types of export, since one file will record what was requested and the other will record exactly what was installed.

To export a requirements-only definition, run a command like the following, where:

  • $env_path is the environment's directory.
  • $definition_path is the environment's directory.

conda env export -p "$env_path" -f "$definition_path" --from-history

To export an all-packages definition, run a command like the following:


conda env export -p "$env_path" -f "$definition_path"
Importing Environments

An environment definition file can be used to recreate an environment in a new location. The target environment does not have to exist, but it may be desirable to first create an empty environment manually to configure options such as package storage location.

To import a definition into a new environment, run a command like the following, where:

  • $definition_path is the environment's directory.
  • $env_path is the environment's directory.

conda env create -f "$definition_path" -p "$env_path"

To import a definition into an existing environment, run a command like the following:


conda env update -f "$definition_path" -p "$env_path"