Pkg Mgmt

Python Environment Skill (Comp Chem & AI Edition)

Default to uv for speed/ML; use mamba for heavy C++/Fortran binaries (e.g., OpenMM).

uv — Fast Project Management (Primary)

Best for: New projects, PyTorch/JAX, RDKit, CI/CD.

uv is an extremely fast Python package installer and resolver written in Rust.

Installation

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with Homebrew
brew install uv

Modern Workflow (Replaces pip/venv)

# Initialize project
uv init my-project && cd my-project

# (Optional) Pin Python version — uv downloads it automatically if missing
uv python pin 3.11

# Add dependencies (updates pyproject.toml & uv.lock)
uv add rdkit pandas torch
uv add --dev pytest ruff

# Sync environment (guarantees reproducibility)
uv sync

# Run commands in the environment
uv run python train_model.py
uv run pytest

The "Quick Experiment"

Run a script with dependencies ephemerally (no permanent env created):

uv run --with rdkit --with matplotlib molecular_vis.py

Legacy Workflow (pip-style)

# Create a virtual environment
uv venv
uv venv --python 3.11  # specific version

# Activate
source .venv/bin/activate

# Install packages
uv pip install rdkit scikit-learn pandas
uv pip install -r requirements.txt
uv pip install -e .

mamba — Complex Binaries (Secondary)

Best for: OpenMM, AmberTools, legacy projects, or strict system library requirements.

mamba is a fast, drop-in replacement for conda.

Installation

# Install miniforge (includes mamba)
# macOS ARM
curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-arm64.sh"
bash Miniforge3-MacOSX-arm64.sh

# macOS Intel
curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-x86_64.sh"
bash Miniforge3-MacOSX-x86_64.sh

# Linux
curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh"
bash Miniforge3-Linux-x86_64.sh

Reproducible Workflow

Always use environment.yml with conda-forge:

# environment.yml
name: md-sim
channels:
  - conda-forge
dependencies:
  - python=3.11
  - openmm
  - ambertools
  - rdkit
  - numpy
  - pandas
  - pip  # Allow pip for pure python packages if needed

# Create from file
mamba env create -f environment.yml

# Update (use --prune to remove deleted deps)
mamba env update -f environment.yml --prune

# Export environment
mamba env export --no-builds > environment.yml

Quick Commands

# Create environment
mamba create -n myenv python=3.11

# Activate/deactivate
mamba activate myenv
mamba deactivate

# Install packages
mamba install rdkit numpy pandas

Decision Matrix: Chemist Edition

The Hybrid Approach

Need mamba binaries (e.g., OpenMM) but want uv speed for everything else? Create the env with mamba, then use uv pip inside it:

mamba create -n hybrid-env openmm python=3.11 -c conda-forge
mamba activate hybrid-env
uv pip install torch rdkit scikit-learn  # Installs into the active Conda env

Best Practices

1. Lockfiles are Mandatory

# uv does this automatically (uv.lock)
uv lock

# For mamba, export without build strings for portability
mamba env export --no-builds > environment.yml

2. pyproject.toml is Truth

Stop using requirements.txt. Define deps in pyproject.toml:

[project]
name = "my-project"
version = "0.1.0"
dependencies = [
    "rdkit",
    "numpy>=1.24",
    "pandas>=2.0",
]

[project.optional-dependencies]
dev = ["pytest", "ruff"]

3. Strict Channels for Mamba

Avoid ABI conflicts by strictly prioritizing conda-forge:

conda config --add channels conda-forge
conda config --set channel_priority strict

4. Never Install to System Python

# Bad
pip install rdkit

# Good
uv venv && source .venv/bin/activate && uv pip install rdkit

CI/CD Pipeline

# GitHub Actions example
- uses: astral-sh/setup-uv@v4
- run: uv sync
- run: uv run pytest