Environment Management¶
Learn how to manage software environments on OSC using modules and virtual environments.
Overview¶
OSC uses two main systems for environment management: 1. Module System: Load pre-installed software 2. Virtual Environments: Isolated Python environments with custom packages
flowchart TD
A{Need custom\nPython packages?} -->|No| B[Modules only]
A -->|Yes| C["uv venv (Recommended)"]
C --> D[uv add / pip install]
C -.->|Need RAPIDS\nGPU preprocessing?| E["See RAPIDS page\n(conda-only)"] Module System¶
What are Modules?¶
Modules are pre-installed software packages maintained by OSC. They handle: - Software dependencies - Environment variables - Library paths - Version management
Basic Module Commands¶
# List available modules
module avail
# Search for specific software
module spider python
module spider pytorch
module spider cuda
# Load a module
module load python/3.12
# Load specific version
module load cuda/12.4
# List loaded modules
module list
# Show module information
module show python/3.12
# Unload a module
module unload python
# Unload all modules
module purge
# Swap modules
module swap python/3.11 python/3.12
Commonly Used Modules¶
Python¶
CUDA (for custom extensions only)¶
Most PyTorch users do NOT need this
PyTorch wheels on PyPI bundle their own NVIDIA libraries. You only need module load cuda if you are compiling custom CUDA extensions (e.g. custom C++/CUDA ops). Run module avail cuda to see available versions.
Git¶
Other Useful Modules¶
Module Dependencies¶
Some modules load dependencies automatically:
Finding Module Information¶
# Search for software
module spider python
# Get detailed info
module spider python/3.12
# Example output shows:
# - Available versions
# - Dependencies required
# - How to load it
Python Virtual Environments¶
Virtual environments isolate project dependencies so different projects can use different package versions without conflicts.
Creating Virtual Environments¶
Method 1: uv (Recommended)¶
uv is the recommended tool for project-level dependency management on OSC. You must use OSC's system Python — not uv's managed Python downloads, which can segfault on RHEL 9.
# Install uv (one-time)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Create a venv using OSC's system Python (critical!)
uv venv --python /apps/python/3.12/bin/python3
# Activate
source .venv/bin/activate
# Install from pyproject.toml
uv sync
# Or add packages directly
uv add numpy pandas matplotlib
uv on OSC: critical caveats
- Always use
--python /apps/python/3.12/bin/python3when creating venvs. uv's standalone Python builds are not compatible with OSC's RHEL 9 libraries and will segfault. - Do NOT load
module load python/3.12and then useuv venv— uv ignores module-loaded Python by default. You must pass the explicit path. - PyTorch from PyPI works — PyPI wheels bundle NVIDIA libraries, so you don't need
module load cuda. But PyG extensions need a flat wheel index configured inpyproject.toml. See PyG Setup for details.
For PyTorch-specific installation (matching CUDA versions, GPU verification), see PyTorch & GPU Setup.
Method 2: venv + pip¶
If you don't use uv, the standard library venv module works fine:
# Load Python module
module load python/3.12
# Create virtual environment
python -m venv ~/venvs/myproject
# Activate environment
source ~/venvs/myproject/bin/activate
# Verify activation (prompt changes)
which python
# Should show: /home/username/venvs/myproject/bin/python
# Install packages
pip install numpy pandas matplotlib
# Deactivate when done
deactivate
Managing Environments¶
List Environments¶
Export/Import Environments¶
# Export requirements (venv + pip)
pip freeze > requirements.txt
# Install from requirements
pip install -r requirements.txt
# uv uses pyproject.toml — no separate export needed
# uv sync installs from pyproject.toml + uv.lock
Organizing Virtual Environments¶
Create a standard structure:
# Create venvs directory
mkdir -p ~/venvs
# Create project-specific environments
python -m venv ~/venvs/project1
python -m venv ~/venvs/project2
python -m venv ~/venvs/ml_research
Legacy: conda (RAPIDS only)
Conda is only needed for RAPIDS GPU preprocessing, which requires conda-only packages. For all other workflows, use uv or venv + pip.
# Load conda
module load python/3.12
# Create conda environment
conda create -n myproject python=3.12
# Activate
conda activate myproject
# Deactivate
conda deactivate
# Remove environment
conda remove -n myproject --all
For RAPIDS setup, see GPU Preprocessing (RAPIDS).
Using Environments in Job Scripts¶
venv in SLURM Job¶
#!/bin/bash
#SBATCH --job-name=my_job
#SBATCH --time=02:00:00
# Load module
module load python/3.12
# Activate virtual environment
source ~/venvs/myproject/bin/activate
# Verify environment
which python
pip list
# Run code
python train.py
# Deactivate (optional, job ends anyway)
deactivate
Multiple Module Loading¶
#!/bin/bash
#SBATCH --job-name=gpu_job
#SBATCH --gpus-per-node=1
# Load all required modules
module purge # Start clean
module load python/3.12
module load cuda/12.4 # Only needed for custom CUDA extensions
module load git
# Activate environment
source ~/venvs/pytorch_gpu/bin/activate
# Run code
python train_gpu.py
Creating Reusable Module Scripts¶
Load Modules Script¶
Create ~/scripts/load_ml_modules.sh:
#!/bin/bash
# Load modules for ML work
module purge
module load python/3.12
# module load cuda/12.4 # Only needed for custom CUDA extensions — PyPI torch bundles CUDA
module load git
echo "Modules loaded for ML work"
module list
Use in job scripts:
Activation Script¶
Create ~/scripts/activate_ml_env.sh:
#!/bin/bash
# Complete environment setup for ML
# Load modules
module purge
module load python/3.12
# module load cuda/12.4 # Only needed for custom CUDA extensions — PyPI torch bundles CUDA
# Activate virtual environment
source ~/venvs/ml_project/bin/activate
# Set environment variables
export PYTHONUNBUFFERED=1
export CUDA_VISIBLE_DEVICES=0
echo "Environment activated"
Use it:
Advanced: Shared Lab Environments
For lab collaboration, create shared environments in project space:
For PyTorch-specific environment setup (CUDA versions, GPU verification, etc.), see PyTorch & GPU Setup.
Managing Disk Space¶
Check Environment Sizes¶
Clean Up¶
# Remove unused venv
rm -rf ~/venvs/old_project
# Clean pip/uv cache
pip cache purge
uv cache clean
# Remove old packages
pip uninstall <package>
Disk Quota¶
.bashrc Convenience Aliases
Add to ~/.bashrc for automatic setup:
# Alias for activating environments
alias activate-ml='source ~/venvs/ml_project/bin/activate'
alias activate-pytorch='source ~/venvs/pytorch/bin/activate'
# Environment variables
export PYTHONUNBUFFERED=1
Warning: Don't load modules in .bashrc that conflict or slow down login.
Best Practices¶
1. Use Descriptive Environment Names¶
# Good
~/venvs/pytorch_gpu_project
~/venvs/transformers_research
~/venvs/computer_vision
# Avoid
~/venvs/env1
~/venvs/test
~/venvs/myenv
2. Document Your Environment¶
Create environment_setup.md in your project:
# Environment Setup
## Environment
- uv venv with Python 3.12
## Setup
\`\`\`bash
uv venv --python /apps/python/3.12/bin/python3
source .venv/bin/activate
uv sync
\`\`\`
3. Keep Dependencies Tracked¶
# pyproject.toml is the preferred dependency specification with uv.
# uv.lock is auto-generated — commit both to git.
git add pyproject.toml uv.lock
git commit -m "Update dependencies"
# If you need a requirements.txt (e.g. for CI or collaborators without uv):
uv pip compile pyproject.toml -o requirements.txt
4. Use Separate Environments per Project¶
Don't share environments between unrelated projects:
5. Test Before Submitting Jobs¶
# Test interactively first
srun -p debug --pty bash
source ~/venvs/myproject/bin/activate
python train.py --epochs 1
# Then submit batch job
Troubleshooting¶
Module Not Found¶
Problem: module: command not found
Solution: Module system not initialized. Check /etc/profile.d/modules.sh is sourced.
Module Load Fails¶
Problem: Module xyz not found
Solutions:
Virtual Environment Not Activating¶
Problem: Environment won't activate
Solutions:
# Verify environment exists
ls ~/venvs/myproject/bin/activate
# Recreate if corrupted
rm -rf ~/venvs/myproject
python -m venv ~/venvs/myproject
Package Installation Fails¶
Problem: pip install fails
Solutions:
# Update pip
pip install --upgrade pip
# Install with user flag
pip install --user package_name
# Check disk quota
quota -s
CUDA Not Available in PyTorch¶
Problem: torch.cuda.is_available() returns False
Verify you're on a GPU node (nvidia-smi) and check torch.cuda.is_available(). If you installed PyTorch from PyPI, you do not need module load cuda -- PyPI wheels bundle CUDA. For full diagnostic steps and PyTorch reinstall commands, see PyTorch & GPU Setup — Troubleshooting.
Conflicting Modules¶
Problem: Modules conflict with each other
Solution:
# Start fresh
module purge
# Load modules in correct order
module load python/3.12
module load cuda/12.4
Quick Reference
# Modules
module load python/3.12 # Load Python
module load cuda/12.4 # Only for custom CUDA extensions (not needed for PyPI torch)
module list # Show loaded
module purge # Unload all
# uv (recommended)
uv venv --python /apps/python/3.12/bin/python3 # Create
source .venv/bin/activate # Activate
uv sync # Install from pyproject.toml
uv add <package> # Add a dependency
# venv + pip
python -m venv ~/venvs/name # Create
source ~/venvs/name/bin/activate # Activate
deactivate # Deactivate
pip freeze > requirements.txt # Export
Secrets and API Keys¶
Never put passwords or API keys in source code. Use environment variables instead:
- Add credential files to
.gitignore - Set restrictive permissions on sensitive data:
chmod 700 ~/projects/sensitive_data
Next Steps¶
- Set up PyTorch on OSC
- Learn Job Submission