Virtual Environment Management

Virtual environments allow you to install specific Python packages for your projects without conflicts. The SMCE supports multiple approaches depending on your workflow and experience level.

With the new EBS home directories, package installation from the command line is much faster than before. See the Storage Overview documentation for more details.

Conda Store (Recommended for Beginners)

Conda Store is a web-based GUI for managing virtual environments. It’s ideal if you’re new to Python package management or prefer visual tools.

Best for:

• Beginners and users who prefer GUI tools

• Creating Jupyter notebook kernels

• Sharing environments with your team

• Accessing pre-built environments

Accessing Conda Store

1. Navigate to File → Hub Control Panel in JupyterHub

2. Click Conda Store in the navigation bar

3. Log in with your SMCE username and password

Creating a New Environment

1. Click New Environment

   • For personal use: create in your personal namespace

   • For team access: use the global namespace (requires admin)

2. Name your environment and add packages using the search interface

   • Conda Store automatically selects compatible Python versions

   • For specific versions, add Python as a package and select the version you need

3. Important: Add the ipykernel package to make your environment available as a Jupyter kernel

4. For Dask Gateway support, also add:

   dask=2025.3.0
   distributed=2025.3.0
   dask-gateway=2025.4.0
   ipywidgets
   

5. Click Create and wait for the build to complete

Note

It may take a few minutes for new environments to appear in JupyterHub. Try stopping and restarting your server if it doesn’t show up.

Editing and Deleting

• Select your environment and click Edit

• Add or remove packages as needed

• To delete, click Delete Environment at the bottom

• Changes may take a minute or two to propagate

Rolling Back Changes

If a package update breaks your environment, you can easily roll back:

1. Select your environment and click Edit

2. Use the Builds dropdown to select a previous build

3. Click Save

Pixi (Recommended for CLI and Projects)

Pixi is a fast, modern package manager that uses the conda ecosystem. It’s ideal for command-line workflows and project-based development.

Best for:

• Git repositories and project-based work

• Fast package installation (seconds vs minutes)

• Reproducible environments shared via git

• CLI-based workflows

Key features:

• Uses conda-forge packages (compatible with conda)

• Creates lock files for exact reproducibility

• Project-based environments

• Works great with the new EBS home directories

Installation

# Install Pixi
curl -fsSL https://pixi.sh/install.sh | bash

# Restart your shell or run:
source ~/.bashrc

# Verify installation
pixi --version

Setting Up a Project

Pixi uses a pixi.toml file to define your project environment. Here’s how to create and use it:

Step 1: Initialize the project

mkdir geospatial-analysis
cd geospatial-analysis
pixi init

This creates a basic pixi.toml file.

Step 2: Edit pixi.toml to add your packages

Open pixi.toml and add your dependencies:

[project]
name = "geospatial-analysis"
channels = ["conda-forge"]
platforms = ["linux-64"]

[dependencies]
python = "3.11.*"
numpy = ">=1.24"
pandas = ">=2.0"
geopandas = ">=0.14"
rasterio = ">=1.3"
matplotlib = ">=3.7"
jupyter = ">=1.0"
ipykernel = ">=6.0"

Step 3: Install the environment

pixi install

This reads pixi.toml, resolves dependencies, creates pixi.lock, and installs packages into .pixi/

Step 4: Use the environment

# Run Jupyter
pixi run jupyter lab

# Run a Python script
pixi run python analyze_data.py

# Start a shell with the environment activated
pixi shell

For git repositories:

• Commit pixi.toml and pixi.lock to git

• Add .pixi/ to your .gitignore

Collaborators can reproduce your exact environment:

git clone <your-repo>
cd <your-repo>
pixi install  # Installs exact same packages from pixi.lock!
pixi run jupyter lab

Using Pixi Environments as Jupyter Kernels

To use your Pixi environment in JupyterLab, you need to register it as a kernel.

Make sure ipykernel is in your pixi.toml dependencies:

[dependencies]
python = "3.11.*"
ipykernel = ">=6.0"
# ... other packages

Then register the kernel:

# From your project directory
pixi shell

# Inside the pixi environment, register as a kernel
python -m ipykernel install --user --name my-project --display-name "My Project (Pixi)"

# Exit the shell
exit

The kernel will now appear in JupyterLab’s kernel selector. You can select it when creating a new notebook or change an existing notebook’s kernel by clicking the kernel name in the top-right corner.

Other Options

Command-Line Conda/Mamba

You can create environments using conda or mamba from the command line. However, Pixi is generally faster and easier for project-based workflows.

Python venv

Python’s built-in venv module works for Python-only projects but doesn’t handle system dependencies or languages like R and Julia.

For most SMCE workflows, we recommend Conda Store (GUI) or Pixi (CLI).