Skip to main content

​
Requirements

PufferLib requires:
  • Python 3.9 or higher (supports 3.9-3.14)
  • PyTorch (for training)
  • NumPy < 2.0
  • CUDA toolkit (optional, for GPU acceleration)

​
Basic installation

Install PufferLib from PyPI: 
pip install pufferlib
This installs the core package with support for:
  • Ocean environments (custom C environments)
  • Vectorization and parallel simulation
  • PufferRL training system
  • Gym, Gymnasium, and PettingZoo compatibility
The basic installation includes dependencies for training: torch, psutil, nvidia-ml-py, rich, imageio, gpytorch, scikit-learn, heavyball, neptune, and wandb.

​
Environment-specific dependencies

PufferLib supports 35+ environments through optional dependency groups. Install only what you need:

​
Atari games

pip install pufferlib[atari]
Includes: gymnasium[accept-rom-license], opencv-python, ale_py

​
Procgen

pip install pufferlib[procgen]
Includes: procgen-mirror (with Python 3.11+ support), stable_baselines3
After installing Procgen, you may need to install glfw==2.7 for some PyTorch versions:
pip install glfw==2.7

​
NetHack

pip install pufferlib[nethack]
Includes: nle==0.9.1, gym, gymnasium

​
MiniGrid

pip install pufferlib[minigrid]
Includes: minigrid==2.3.1, gym, gymnasium

​
Mujoco

pip install pufferlib[mujoco]
Includes: gymnasium[mujoco], moviepy

​
PettingZoo environments

# Butterfly environments
pip install pufferlib[butterfly]

# Multi-agent Atari
pip install pufferlib[atari]

​
Other supported environments

PufferLib includes optional dependencies for:
  • avalon - Avalon RL environment
  • box2d - Box2D physics environments
  • bsuite - DeepMind BSuite
  • crafter - Crafter survival game
  • craftax - Craftax (JAX-based)
  • dm_control - DeepMind Control Suite
  • griddly - Griddly grid world
  • kinetix - Kinetix environments
  • minihack - MiniHack (NetHack variants)
  • nmmo - Neural MMO
  • pokemon_red - Pokemon Red GB
  • vizdoom - ViZDoom FPS
See the full list in pyproject.toml for all supported environments.

​
Installing from source

For development or the latest features:
1

Clone the repository

git clone https://github.com/PufferAI/PufferLib.git
cd PufferLib
2

Install in editable mode

pip install -e .
This builds the C extensions for Ocean environments and CUDA kernels (if available).
3

Install optional dependencies

pip install -e ".[atari,procgen,nethack]"
Building from source requires build tools: setuptools, wheel, Cython, numpy<2.0, and torch.

​
CUDA extensions

PufferLib includes CUDA-accelerated kernels for advantage computation. These are automatically built if:
  1. PyTorch is compiled with CUDA or ROCm support
  2. CUDA toolkit or ROCm is found on your system

​
Building without CUDA

If you don’t have CUDA but still want to install PufferLib: 
pip install pufferlib --no-build-isolation
The package will build CPU-only versions of the extensions.

​
Force rebuild

To rebuild extensions after updating PyTorch or CUDA: 
pip install --force-reinstall --no-cache-dir pufferlib

​
Troubleshooting CUDA builds

If you encounter CUDA build errors:
Ensure nvcc is in your PATH:
export PATH=/usr/local/cuda/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH
Verify your PyTorch installation matches your CUDA version:
python -c "import torch; print(torch.version.cuda)"
Install the correct PyTorch version from pytorch.org.
Some systems require disabling build isolation:
pip install pufferlib --no-build-isolation
CUDA requires compatible GCC versions. For CUDA 11.x, use GCC 9 or 10:
export CC=gcc-9
export CXX=g++-9
pip install pufferlib

​
Building Ocean environments

Ocean environments are PufferLib’s custom C-based environments. They’re built automatically during installation. To skip building Ocean environments: 
NO_OCEAN=1 pip install pufferlib
To build only specific Ocean environments: 
python setup.py build_breakout
python setup.py build_asteroids

​
Verifying installation

Test your installation: 
import pufferlib
import pufferlib.ocean
import pufferlib.vector
from pufferlib import pufferl

print(f"PufferLib version: {pufferlib.__version__}")

# Test Ocean environment
env_creator = pufferlib.ocean.env_creator('puffer_breakout')
vecenv = pufferlib.vector.make(env_creator, num_envs=4, num_workers=2)
vecenv.reset()
print("Ocean environment: OK")

# Test CUDA extensions
try:
    from pufferlib import _C
    print("CUDA extensions: OK")
except ImportError:
    print("CUDA extensions: Not available (CPU only)")
Expected output: 
PufferLib version: 3.0
Ocean environment: OK
CUDA extensions: OK

​
Docker installation

For a pre-configured environment: 
docker pull pufferai/pufferlib:latest
docker run -it --gpus all pufferai/pufferlib:latest

​
Next steps

Quickstart

Train your first agent

Core concepts

Learn PufferLib fundamentals

Build docs developers (and LLMs) love

Get started for freeTalk to us