Conda

Conda is an open source package management system.

External Links
Conda website
Conda: User Guide





Contents


• Loading and initializing Conda
• Installing and activating a Conda environment
• Running a Conda installed application
• Warning: multithreading and MPI applications
• Tips and Troubleshooting
• What is a Conda environment anyway???

Loading and Initializing Conda

Before using Conda, the following two steps are required. Conda must be initialized, and a .condarc must be created. The default shell for the new Hazel cluster is bash (however the tcsh shell is also available, type "tcsh").

If your home directory is at or over-quota from an improperly configured conda, see this page for help.

1) Initialize Conda environment:

This step is necessary only once for an HPC user, unless the initialization settings are removed.

To load the system installed Conda, load the module and use init to add it to the path. Normally using a login file to automatically set the environment is strongly discouraged, but in the case of Conda, many features cannot be used without setting this initialization file. Log out and then back in again after using conda init.

module load conda
conda init bash
[ignore the warnings, log out then back in again]

Optional - remove old environments:

For users who have already been using different Conda environments and would like to begin installing with the new recommended procedures, clean out the remnants of old Conda environments by doing the following.

Check for these 'dot' files:

cd ~
more .bashrc
more .tcshrc

If these files contain information for old Conda environments, edit the files and delete this section:

# >>> conda initialize >>>
(stuff)
# >>> conda initialize >>>

2) Create a .condarc file:
This step is mandatory: Conda will fill the quota of the home directory if pkgs_dirs is not set in this file.

By default, Conda stores packages in the /home directory. The /home directory is too small for that, and the packages are only needed temporarily. They should not be saved, taking up space in permanent directories. To change the default location to /share, use a text editor to create a file called .condarc. The path to that file should be /home/$USER/.condarc and it should contain the path to the alternative location, e.g.:

pkgs_dirs:
 - /share/$GROUP/$USER/conda/pkgs

In addition, many packages require adding a 'channel'. Common channels may be added before creating environments by editing the .condarc.

• To add channels, add them to ~/.condarc. For example, the bioconda and conda-forge channels may be added by adding the following lines to ~/.condarc:

  channels:
    - bioconda
    - conda-forge
  

The following displays a sample .condarc file:

[unityid@login01 ~]$ cd
[unityid@login01 ~]$ more .condarc
pkgs_dirs:
  - /share/group_name/unityid/conda/pkgs
channels:
  - bioconda
  - conda-forge

Installing and activating a Conda environment

Before installing any software, including a Conda environment, request a space for user maintained software to be used by all members of a Project. The path for that space is generally /usr/local/usrapps/groupname.

If conda is failing to install your packages, then delete the cache folder at /share/$GROUP/$USER/conda/pkgs. You may want to double check you have not manually put any important files in this directory before deleting it.

The following is the general idea of how to use Conda. Please use a YAML file to avoid package conflicts. See below for details.

To install Conda environments, specify a prefix, which will be the path to where the environment will be installed. Choose a descriptive name for the environment - Conda will create the directory, the directory should not already exist. For example, to create a Conda environment called env_ABC containing the packages AAA, BBB, and CCC, and install it in the directory /usr/local/usrapps/[groupname][username], do :

conda create --prefix /usr/local/usrapps/$GROUP/$USER/env_ABC AAA BBB CCC

To activate the environment, do:

conda activate /usr/local/usrapps/$GROUP/$USER/env_ABC

Once in a Conda environment, a user can install additional packages using either conda install or pip install (after doing conda install pip); however, this is not recommended, as it is harder when doing so to maintain an environment where all software is compatible.

Best practice is to create a YAML file with all of the desired Conda packages. Conda will 'solve' the environment, that is, it will find a configuration where all desired packages are the correct version numbers to work together, assuming such a configuration exists. If a user needs a version of one software that is not compatible with another, then they would create two different Conda environments. When updating, create a new environment and do not delete the old version without thoroughly testing the new one.

To create a Conda environment from a YAML file called ABC.yml, do

conda env create --prefix /usr/local/usrapps/$GROUP/$USER/env_ABC -f ABC.yml

The YAML file will contain a name, a list of Conda channels to look for the packages, and a list of all the desired packages.
Here are some sample YAML files:
• datascience.yml - Contains many common data science programs
• sklearn.yml - Machine learning with scikit-learn
• biotools.yml - Contains applications for a bioinformatics workflow
• ncdfutil.yml - Used in sponsored software group ncdfutil, contains many NetCDF Utilities
• rlibs.yml - Used to create an environment with custom R libraries

When Conda creates an environment, it finds a configuration such that all of the packages/dependencies are compatible. If a great many packages are added to a YAML file, it might be impossible for Conda to resolve the necessary environment. In that case, multiple Conda environments will need to be created.

To deactivate the environment, do:

conda deactivate

Running a Conda installed application

Activating a Conda environment sets the compute environment, and is similar to loading a module. Here is a sample batch script that uses an application called mycode that was installed via a Conda environment:

#!/bin/bash
#SBATCH --ntasks=1
#SBATCH --time=02:00:00
#SBATCH --job-name=mycode
#SBATCH --output=stdout.%j
#SBATCH --error=stderr.%j
source ~/.bashrc
conda activate /usr/local/usrapps/groupname/username/env_mycode
mycode
conda deactivate

NOTE: The "source ~/.bashrc" in the bash job script is necessary. You may run into issues if you don't have it before the "conda activate ......" command.

Warning: multithreading and MPI applications

• Multi-threading: Many of the applications available in Conda environments are automatically run in parallel, that is, they may auto-detect the number of cores on the nodes and spawn the same number of tasks. See the following for more information on testing, and contact HPC Staff for further assistance.
• Using MPI: Conda is package management system that installs applications and all of their dependencies. That means that if an installed package requires MPI, Conda will install its own MPI. User installed MPI will not work properly with Slurm, therefore a user must use the system MPI. See the following documentation for of using system MPI to install R or Python packages requiring MPI.

  Tips and Troubleshooting

• Full home directory: If your home directory is full from an improperly configured conda, see this page for help.
• Conda package installations fail: If conda is failing to install your packages, then delete the cache folder at /share/$GROUP/$USER/conda/pkgs. You may want to double check you have not manually put any important files in this directory before deleting it.
• To list the available packages contained in an activated Conda environment, do conda list.
• Alternate versions of Python and various packages may be specified by following the package name with =version.number, e.g. matplotlib=3.1.
• All installations must be done from a login node. Packages cannot be downloaded from a compute node, and neither a compute node nor an HPC-VCL node can write to /usr/local/usrapps.
• Use a YAML file! If you create a Conda environment and then attempt to add something to it, Conda may not be able to reconcile the existing applications and libraries with the new application. This is common in R or Python, when newer versions or libraries only work with newer releases. It also happens when attempting to install an older package into an existing environment. For example, older packages may need Python 2, and therefore cannot be used with a Python 3 environment. The message will say "solving environment" and it will continue for quite some time before eventually giving up. If this happens, create a new environment that includes the new application. (Keep the old environment!)
• Create multiple environments rather than adding to them. Using conda install on an existing environment may break that environment, resulting in your scripts suddenly not working anymore.
• Check your syntax: don't forget either the 'env' or the '-f' in the conda env create --prefix /path/to/env_ABC -f ABC.yml.
• PackagesNotFoundError: If you get this error, first check your syntax. Next, make sure the package exits, and if so, which channel or channels it is available from. Some Python packages are not available through Conda, and some Conda packages are only available through specific channels. You can find this information by searching for the package name on the Anaconda.org search page.
• The instructions use 'pip install'. Some packages are only available through GitHub or some other website or collaborator. In this case, go to the website for the package and carefully read the instructions. Create a YAML file with all of the dependencies listed in the instructions, including version numbers when indicated, and also include any additional applications or Python packages that you will use while doing your workflow. After creating and activating the Conda environment from the YAML file, follow the remaining instructions for the "pip install". The packages installed by pip will then be available when you activate that Conda environment.
• Python notebooks on the HPC-VCL: If the application includes examples using IPython or Jupyter notebook, they can be tested using the HPC-VCL. See these instructions for requesting access to and using the HPC-VCL.
  To add Jupyter notebook to a Conda environment, add 'notebook' to the dependencies in the YAML file:

   - notebook
  

• Python notebooks on a compute node: Jupyter runs in your browser, but the actual computation happens on a Hazel compute node, not your laptop. Connecting the two takes a few one-time setup steps below.

  Workflow: login node → compute node (salloc) → Jupyter server on that node → SSH tunnel → browser.

  (1) Log in to Hazel.
  (2) Request a compute node. A login node cannot run code, so request (and log in to) a compute node:

   salloc --ntasks=4 --nodes=1 --time=08:00:00
  

  This requests an interactive job (salloc) with four cores (--ntasks=4) on one node (--nodes=1) for 8 hours (--time=08:00:00). Adjust the core count, time limit, or queue as needed.
  (3) Note the compute node's name. Once dispatched, the terminal logs you in to the compute node:

  Job <387980> is submitted to default queue single_chassis.
  Waiting for dispatch ...
  Starting on nxxx
  (base) [username@nxxx your-directory]$
  

  The node name (nxxx above) is the HOSTNAME you'll need in step 7 — make a note of it.
  (4) Activate the Conda environment that has Jupyter Notebook installed:

  conda activate /share/$GROUP/$USER/group2_env
  

  (5) Launch the notebook server:

  jupyter notebook --no-browser --port=1113 --ip=0.0.0.0
  

  Pick any 4-digit --port value (1113 here) — this is the HOSTPORT you'll need in step 7. The terminal pauses, then prints a link containing a "token".
  (6) Copy the token URL from that output, for example:
  http://nxxx:1113/?token=ae7f7ea974d4d80f94c247e0a4bda5c3acb5408583e33a38
  Don't open it yet — the tunnel still needs to be set up first.
  (7) On your local machine (WSL, PowerShell, or macOS Terminal), open a new terminal and start an SSH tunnel:

  ssh -N -L LOCALPORT:HOSTNAME:HOSTPORT UNITYID@login.hpc.ncsu.edu
  

  • LOCALPORT — any 4-digit number you choose, e.g. 9999
  • HOSTNAME — the compute node name from step 3, e.g. nxxx
  • HOSTPORT — the Jupyter port from step 5, e.g. 1113
  • UNITYID — your Hazel login ID
  Using the example values above:

  ssh -N -L 9999:nxxx:1113 username@login.hpc.ncsu.edu
  

  (8) Enter your password when prompted. The terminal will then go unresponsive — that's expected, it means the tunnel is active. Leave this window open.
  (9) Open the notebook in your browser. Take the token URL from step 6 and replace the part between http:// and /? with localhost:LOCALPORT (your choice from step 7). Using the example values:
  http://localhost:9999/?token=ae7f7ea974d4d80f94c247e0a4bda5c3acb5408583e33a38
  Paste this into Chrome or Safari to open Jupyter, where you can create and run notebooks.
  (10) When you're done: click "Quit" on the Jupyter homepage, or go to the terminal running Jupyter and press Ctrl+C (then confirm "yes"). Exit the compute node by typing exit. Close the tunnel terminal from steps 7–8 with Ctrl+C.
  To confirm Jupyter is actually running on the compute node, run this in a notebook cell:

  import platform
  platform.node()
  

  It should return the same node name you noted in step 3.

What is a Conda environment anyway???

• Most of the time, Conda installs applications by downloading precompiled binaries from package repositories. Sometimes it downloads source code, and then compiles it on Hazel, in which case other modules or packages may need to be installed or linked - for example, you may need to load the CUDA modules for ML/AI packages.
• The transient files (tar balls, source code, etc.) are downloaded to a temporary directory, which was defined in the .condarc in 'pkgs_dirs'. If that is not set, the default is to download to the home directory. The home directory is too small for this, and as these packages are intermediate products, they should not be saved to a directory with limited space or that is backed up. Don't waste permanent storage on it - put it in /share, as shown by the example .condarc file.
• After downloading, the applications will be installed to a location defined by '--prefix', which generally should be set to the project's space in /usr/local/usrapps/$GROUP.
• Conda creates the equivalent of a module, and 'conda activate' does the equivalent of 'module load', i.e., it sets variables such as PATH and LD_LIBRARY_PATH to point to the proper locations in '--prefix'. (See more about environment variables here.)

Last modified: September 01 2026 21:22:40.