Skip to main content

Normalizing Flows Made Easy

Zuko is a Python package that implements normalizing flows in PyTorch. Build conditional distributions with trainable parameters that integrate seamlessly with your neural networks.

Why Zuko?

Zuko solves fundamental problems with PyTorch’s distributions by introducing LazyDistribution and LazyTransform — modules whose forward pass returns distributions and transformations. This design enables conditional flows while maintaining full nn.Module compatibility.

PyTorch Integration

Full nn.Module support with GPU acceleration and parameter management

Conditional Flows

Express conditional distributions p(x|c) naturally and efficiently

Rich Architecture Library

12+ flow architectures from NSF to CNF, all ready to use

Flexible Composition

Build custom flows by composing transformations and distributions

Quick Example

Train a Neural Spline Flow to model a conditional distribution in just a few lines:
import torch
import zuko

# Create a flow with 3 sample features and 5 context features
flow = zuko.flows.NSF(3, 5, transforms=3, hidden_features=[128] * 3)

# Train to maximize log-likelihood
optimizer = torch.optim.Adam(flow.parameters(), lr=1e-3)

for x, c in trainset:
    loss = -flow(c).log_prob(x)  # -log p(x | c)
    loss = loss.mean()
    
    optimizer.zero_grad()
    loss.backward()
    optimizer.step()

# Sample from the learned distribution
x = flow(c_star).sample((64,))

Available Flow Architectures

Zuko includes implementations of major normalizing flow architectures from recent research:

NSF

Neural Spline Flows (2019)

MAF

Masked Autoregressive Flow (2017)

RealNVP

Real-valued Non-Volume Preserving (2016)

NICE

Non-linear Independent Components (2014)

CNF

Continuous Normalizing Flows (2018)

NAF

Neural Autoregressive Flows (2018)

Get Started

Installation

Install Zuko via pip or from source

Quickstart Guide

Train your first normalizing flow in 5 minutes

Core Concepts

Learn about normalizing flows and lazy distributions

API Reference

Explore the complete API documentation

Build docs developers (and LLMs) love