Installation

Prerequisites

Python 3.14
PDM package manager
AWS CLI v2+ or rclone (for S3 data access)
Hugging Face Token (for model weights and pre-extracted features)
NVIDIA GPU + CUDA or Apple Silicon Mac (MPS) — optional but recommended

Quick Install


pip install --user pdm    # install PDM if not already installed
 
# Install all dependencies + PyTorch for your hardware (choose one):
pdm install-pytorch-cu128    # CUDA 12.8 (recommended for most GPUs)
pdm install-pytorch-cu130    # CUDA 13.0
pdm install-pytorch-cpu      # CPU-only (no GPU)

This single command installs all project dependencies, PyTorch with the correct backend, and dev tools (pytest, ruff, mypy).

HPC Cluster Setup (Conda)

For HPC environments where Python 3.14 is not available system-wide:


# Create a conda environment with Python 3.14
conda create -n morphoclip python=3.14 -y
conda activate morphoclip
 
# Fix libstdc++ version mismatch (common on HPC nodes)
conda install -c conda-forge libstdcxx-ng
export LD_LIBRARY_PATH=$CONDA_PREFIX/lib:$LD_LIBRARY_PATH
 
# Install PyTorch (pick the CUDA version matching your HPC — check with nvidia-smi)
pip install --index-url https://download.pytorch.org/whl/cu126 torch torchvision
# or: pip install --index-url https://download.pytorch.org/whl/cu128 torch torchvision
 
# Install remaining dependencies
pip install datasets transformers huggingface-hub rich pandas seaborn matplotlib \
    scipy scikit-image python-dotenv Pillow numpy PyYAML opencv-python
 
# Set HF cache to project space (avoids home directory quota issues)
export HF_HOME=/path/to/your/project/.hf_cache

Verify your setup:


python sanitycheck/check_gpu.py          # confirms CUDA detected
python sanitycheck/check_setup.py --device auto