Skip to main content

​
Requirements

Zuko requires:
  • Python: 3.10 or higher
  • PyTorch: 1.12.0 or higher
  • NumPy: 1.20.0 or higher
Zuko is built on top of PyTorch and leverages its distribution and transformation primitives. Make sure you have PyTorch installed before installing Zuko.

​
Installation Methods

1

Install from PyPI (Recommended)

The easiest way to install Zuko is via pip from PyPI:
pip install zuko
This will install the latest stable release along with all required dependencies.
2

Install from Source (Latest Features)

If you need the latest features that haven’t been released yet, install directly from the GitHub repository:
pip install git+https://github.com/probabilists/zuko
Installing from source gives you access to the latest development features, but may be less stable than the PyPI release.
3

Development Installation

If you want to contribute to Zuko or modify the source code, clone the repository and install in editable mode:
git clone https://github.com/probabilists/zuko.git
cd zuko
pip install -e .
For development with additional tools:
# Install with development dependencies
pip install -e ".[dev]"

# Or install all optional dependencies
pip install -e ".[dev,docs,test]"

​
Verify Installation

After installation, verify that Zuko is installed correctly: 
import zuko
import torch

print(f"Zuko version: {zuko.__version__}")
print(f"PyTorch version: {torch.__version__}")

# Test basic functionality
flow = zuko.flows.NSF(features=2, context=0, transforms=3)
print(f"Created flow: {type(flow).__name__}")

# Sample from the flow
samples = flow().sample((10,))
print(f"Generated samples with shape: {samples.shape}")
Expected output: 
Zuko version: 1.5.0
PyTorch version: 2.x.x
Created flow: NSF
Generated samples with shape: torch.Size([10, 2])

​
GPU Support

Zuko automatically leverages PyTorch’s GPU support. If you have a CUDA-capable GPU, you can move flows to GPU just like any PyTorch module: 
import torch
import zuko

# Create a flow
flow = zuko.flows.NSF(features=3, context=5)

# Move to GPU
if torch.cuda.is_available():
    flow = flow.to('cuda')
    print("Flow moved to GPU")
else:
    print("No GPU available, using CPU")

​
Optional Dependencies

Zuko has several optional dependency groups:
GroupInstall CommandPurpose
devpip install zuko[dev]Development tools (pre-commit, ruff, matplotlib)
docspip install zuko[docs]Documentation building (sphinx, myst-nb)
testpip install zuko[test]Testing framework (pytest)

​
Common Issues

If you encounter issues with PyTorch compatibility:
# Check your PyTorch version
python -c "import torch; print(torch.__version__)"

# Upgrade PyTorch if needed
pip install --upgrade torch
If you can’t import Zuko after installation:
# Verify the installation
pip show zuko

# Reinstall if necessary
pip uninstall zuko
pip install zuko
If you have problems with GPU acceleration:
import torch

print(f"CUDA available: {torch.cuda.is_available()}")
print(f"CUDA version: {torch.version.cuda}")
print(f"Device count: {torch.cuda.device_count()}")
Make sure you have the CUDA-enabled version of PyTorch installed. See PyTorch installation guide for details.

​
What’s Next?

Now that you have Zuko installed, you’re ready to build your first normalizing flow!

Quickstart Tutorial

Learn how to create and train a normalizing flow in just a few minutes

Build docs developers (and LLMs) love

Get started for freeTalk to us