Skip to content

Installation Guide

Detailed installation instructions for various setups.

System Requirements

Minimum Requirements

  • OS: Linux, macOS, Windows (WSL recommended)
  • Python: 3.9 or higher
  • RAM: 8GB minimum, 16GB recommended
  • Storage: 10GB for models and datasets
  • GPU: NVIDIA GPU with 8GB+ VRAM (for training)
  • RAM: 32GB
  • Storage: 50GB+ SSD
  • Python: 3.11

Installation Methods

Method 1: From Source (Development)

Best for contributors and development:

# Clone repository
git clone https://github.com/zooai/gym.git
cd gym

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in editable mode
pip install -e .

# Install development dependencies
pip install -r requirements-dev.txt

Method 2: From PyPI (Stable)

For production use:

pip install zoo-gym

Method 3: From Docker

Pre-configured environment:

# Pull image
docker pull zooai/gym:latest

# Run container
docker run -it --gpus all -p 7860:7860 zooai/gym:latest

# Or build from source
docker build -t gym -f docker/Dockerfile .
docker run -it --gpus all -p 7860:7860 gym

Method 4: From Conda

Isolated environment:

# Create environment
conda create -n gym python=3.11
conda activate gym

# Install PyTorch (choose your CUDA version)
conda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia

# Install Gym
pip install zoo-gym

GPU Setup

NVIDIA CUDA

For NVIDIA GPUs with CUDA support:

# Install PyTorch with CUDA 11.8
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# Or CUDA 12.1
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# Verify CUDA
python -c "import torch; print(torch.cuda.is_available())"

AMD ROCm

For AMD GPUs:

# Install PyTorch with ROCm
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm5.7

Apple Silicon (M1/M2/M3)

For Apple Silicon Macs:

# Install PyTorch with MPS support
pip install torch torchvision torchaudio

# Verify MPS
python -c "import torch; print(torch.backends.mps.is_available())"

CPU Only

For CPU-only systems:

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

Optional Dependencies

Significantly speeds up training:

pip install flash-attn --no-build-isolation

DeepSpeed (Multi-GPU)

For distributed training:

pip install deepspeed

BitsAndBytes (Quantization)

For QLoRA and 4-bit training:

pip install bitsandbytes

vLLM (Fast Inference)

For high-throughput serving:

pip install vllm

Unsloth (2x Faster)

Optimized training kernels:

pip install unsloth

Verification

Check Installation

# Version check
python -c "import gym; print(gym.__version__)"

# GPU check
python -c "import torch; print(f'CUDA: {torch.cuda.is_available()}')"

# Full system check
gym doctor

Run Tests

# Install test dependencies
pip install pytest pytest-cov

# Run tests
pytest tests/

# With coverage
pytest tests/ --cov=gym --cov-report=html

Environment Variables

Configure Gym behavior:

# HuggingFace token (for gated models)
export HF_TOKEN=your_token_here

# Cache directory
export HF_HOME=/path/to/cache

# Mirror (China users)
export HF_ENDPOINT=https://hf-mirror.com

# DeepSeek API (for Continuous Learning)
export DEEPSEEK_API_KEY=your_key_here

# Logging
export PYTHONPATH=/path/to/gym:$PYTHONPATH
export LOG_LEVEL=INFO

Troubleshooting

Import Error: No module named 'gym'

Reinstall in development mode: 

pip uninstall zoo-gym
pip install -e .

CUDA Version Mismatch

Check CUDA version: 

nvidia-smi  # Shows installed CUDA
nvcc --version  # Shows CUDA toolkit version

Reinstall matching PyTorch: 

pip uninstall torch torchvision torchaudio
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

Flash Attention Build Fails

Use pre-built wheels: 

pip install flash-attn --no-build-isolation \
  --find-links https://github.com/Dao-AILab/flash-attention/releases

Out of Memory

Use QLoRA with 4-bit quantization: 

gym train \
  --quantization_bit 4 \
  --double_quantization \
  --finetuning_type lora

Slow Downloads

Use HuggingFace mirror: 

export HF_ENDPOINT=https://hf-mirror.com

Or download manually: 

huggingface-cli download Qwen/Qwen3-4B-Instruct --local-dir ./models/qwen3-4b

Uninstallation

# Remove package
pip uninstall zoo-gym

# Remove cache
rm -rf ~/.cache/huggingface

# Remove virtual environment
deactivate
rm -rf .venv

Next Steps

Need help? Join our Discord or open an issue!