Pufferlib

PufferLib

Use PufferLib with an explicit version profile. Upstream currently has two

incompatible surfaces:

| Profile | Status on 2026-07-23 | Main use |

|---|---|---|

| pufferlib==3.0.0 | Latest stable PyPI release, published 2025-06-23 | Python/Gymnasium/PettingZoo emulation, pufferlib.vector, Torch PuffeRL |

| source 4.0 | Upstream default branch; not the latest stable PyPI artifact | Native C Ocean environments, native CUDA trainer, optional Torch fallback |

Do not combine 3.0 imports with 4.0 config/CLI examples. The 4.0 redesign

removed the 3.0 emulation, vector, and pytorch modules from the current

package tree.

Safe defaults

• Start with bundled synthetic, CPU-only, network-free tools.
• Do not import an arbitrary environment by dotted path. Bundled tools accept

only allowlisted built-ins and slug identifiers.

• Do not install or execute an unreviewed environment package, native

extension, ROM, map, checkpoint, or pickle file.

• Verify official source, immutable revision, licenses, checksums or

attestations, and build hooks. Sandbox native builds and first execution.

• Cap steps, environments, agents, workers, threads, buffers, memory, disk,

render size, and wall time.

• Keep training and evaluation environments/seeds separate.
• Default logging to local/none. External logging requires explicit opt-in,

disclosure acknowledgment, and separate artifact-upload approval.

• Never pass W&B or Neptune credentials via CLI, INI, JSON, tags, run names, or

logger configuration. Never print them.

• Never dump all environment variables or recursively search for .env.

10. Hash checkpoint bytes before trusted, sandboxed loading; metadata inspection

is not proof of safety.

First local checks

All bundled CLIs are dependency-free and emit strict JSON:

python3 scripts/env_template.py --help
python3 scripts/env_contract_validator.py
python3 scripts/benchmark_vectorization.py --backend serial
python3 scripts/train_template.py
python3 scripts/validate_plan.py
python3 scripts/repro_plan.py

Defaults are synthetic, deterministic, bounded, local, CPU-only, no-network,

and dry-run where training would otherwise occur.

Installation and provenance

Published 3.0.0

PyPI supplies only pufferlib-3.0.0.tar.gz:

sha256: 7df3a3e3f5f894d78d2a1f5374097890aec01473183e748abefe4f3faa10eaa9
Requires-Python: >=3.9

After source/build review, create a pinned uv project:

uv venv --python 3.11
uv add --exact --no-sync "pufferlib==3.0.0"
uv lock
uv sync --frozen

Commit pyproject.toml and uv.lock; verify the archive digest and every

resolved dependency. The source build can compile native code and fetch build

assets, so resolve/build in a sandbox without credentials or sensitive mounts.

The uploaded metadata does not pin Torch or CUDA; do not claim a supported CUDA

matrix that PyPI does not declare.

Current 4.0 source

The reviewed branch head on 2026-07-23 was:

25647630e1b15330bb3153a5a0d3ff8d234c3acf

Pin the commit, not branch 4.0:

uv add --no-sync \
  "pufferlib @ git+https://github.com/PufferAI/PufferLib.git@25647630e1b15330bb3153a5a0d3ff8d234c3acf"
uv lock

The current package declares Python >=3.10 and Torch >=2.9. Upstream

PufferTank currently uses Ubuntu 24.04, Python 3.12, and an NVIDIA CUDA

13.0.2/cuDNN development image with the cu130 Torch index, but does not pin

the exact Torch wheel or all system packages. Treat it as a reference, not a

complete lock. Never execute a remote installer directly from a pipe.

Read references/training.md before any installation or build.

Environment workflow

1. Validate the contract

Gymnasium reset returns (observation, info). Step returns:

(observation, reward, terminated, truncated, info)

Validate spaces, shapes, dtypes, finite rewards, booleans, reset-before-step,

reset-after-end, seeding, and cleanup. terminated is an MDP terminal;

truncated is an external cutoff such as a time limit. Preserve the distinction

for bootstrapping and metrics.

python3 scripts/env_contract_validator.py \
  --steps 64 --episodes 8 --seed 42

2. Adapt only after review

Published 3.0 uses explicit wrappers:

import pufferlib.emulation

wrapped = pufferlib.emulation.GymnasiumPufferEnv(reviewed_gymnasium_instance)

For a reviewed PettingZoo Parallel environment:

wrapped = pufferlib.emulation.PettingZooPufferEnv(reviewed_parallel_instance)

There is no supported 3.0 pufferlib.emulate(...) shortcut matching the old

skill. Read references/environments.md and references/integration.md.

3. Native environments

Published 3.0 PufferEnv requires

single_observation_space, single_action_space, and num_agents before

super().__init__(buf). It uses in-place vector buffers and returns separate

terminal/truncation arrays plus a list of info dictionaries.

Current 4.0 uses C bindings. Start from upstream ocean/squared (single-agent)

or ocean/target (multi-agent), build one environment in local/sanitized mode,

and verify every buffer size/type/index before optimization.

Vectorization workflow

Published 3.0:

import pufferlib.vector

vecenv = pufferlib.vector.make(
    reviewed_creator,
    backend=pufferlib.vector.Serial,
    num_envs=4,
    seed=42,
)

Move to Multiprocessing only after serial traces pass. Record

num_envs, num_workers, batch_size, zero-copy mode, start method, agent

count, masks, and actual returned shapes. For multi-agent environments, batch

length is based on agent slots, not necessarily num_envs.

Current 4.0 config instead uses:

[vec]
total_agents = 4096
num_buffers = 2
num_threads = 16

Read references/vectorization.md. Benchmark fixed work with warmup and at least

three repeats; report simulation and end-to-end training SPS separately. The

bundled benchmark measures only its synthetic harness.

Policy workflow

Published 3.0 policies are Torch modules sized from

single_observation_space/single_action_space. Stable recurrent composition

uses encode_observations and decode_actions; structured emulation uses

pufferlib.pytorch.nativize_dtype and nativize_tensor.

Current 4.0 Torch fallback composes:

pufferlib.models.Policy(encoder=encoder, decoder=decoder, network=network)

It provides MLP, MinGRU, LSTM, and GRU network choices; --slowly selects this

fallback instead of the native backend. Check output/state shapes, masks,

finite values, gradients, and eager-versus-compiled behavior. See

references/policies.md.

Training and evaluation

Published 3.0 trainer import:

from pufferlib import pufferl

trainer = pufferl.PuffeRL(train_config, vecenv, policy)

Current 4.0 CLI:

puffer train ENV_NAME
puffer eval ENV_NAME --load-model-path EXACT_TRUSTED_PATH
puffer sweep ENV_NAME

Generate a plan instead of launching by default:

python3 scripts/train_template.py \
  --profile pypi-3.0.0 \
  --environment synthetic \
  --device cpu \
  --total-timesteps 10000

Validate a custom strict-JSON plan:

python3 scripts/validate_plan.py --root . --config plan.json

The schema rejects secret-bearing keys, unbounded resources, dotted environment

paths, invalid vector divisibility, mixed-version options, and coupled

train/eval seeds. See references/training.md.

Logging

PufferLib 3.0 exposes W&B and Neptune; current 4.0 CLI exposes W&B. Both are

optional external services. They may transmit configuration, metrics, source

metadata, hardware telemetry, output, and approved artifacts, with privacy,

retention, access-control, and cost implications.

• W&B credential: named environment variable WANDB_API_KEY.
• Neptune credential: named environment variable NEPTUNE_API_TOKEN.
• Never put values in arguments/config/logs.
• Sanitize config keys before logging.
• Keep source/model upload off unless explicitly approved.

The planner requires both:

python3 scripts/train_template.py \
  --logger wandb \
  --enable-external-logging \
  --acknowledge-external-disclosure

It reports only the required variable name and never reads its value.

Checkpoint workflow

PufferLib 3.0 and the 4.0 Torch fallback use Torch serialization; current native

4.0 writes opaque .bin weights. PyTorch warns that untrusted models are

programs and that torch.load uses unpickling.

python3 scripts/inspect_checkpoint.py checkpoint.pt \
  --root . \
  --expected-sha256 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

The inspector hashes and classifies only. It does not call torch.load, import

pickle/Torch, inspect archive members, or extract files. Verify source, license,

architecture, environment revision, sidecar metadata, and checksum before any

sandboxed load. Never use latest in a reproducible evaluation.

Bundled files

Scripts

• scripts/env_template.py — deterministic synthetic Gymnasium-style template.
• scripts/env_contract_validator.py — bounded contract and seed checks.
• scripts/benchmark_vectorization.py — capped serial/spawn synthetic benchmark.
• scripts/train_template.py — non-executing 3.0/4.0 training-plan generator.
• scripts/validate_plan.py — strict config/resource/security validator.
• scripts/inspect_checkpoint.py — metadata/hash inspection without deserialization.
• scripts/repro_plan.py — separate-seed evaluation and benchmark plan.

References

• references/environments.md — Gymnasium, stable PufferEnv, emulation, native C.
• references/vectorization.md — backends, shapes, start methods, benchmarks.
• references/policies.md — stable/current policy contracts and state safety.
• references/training.md — installs, config, CLI, PuffeRL, eval, logs, checkpoints.
• references/integration.md — migration matrix, third-party and credential safety.

Dated upstream sources

• PyPI pufferlib 3.0.0 —

released 2025-06-23; checked 2026-07-23.

• PyPI 3.0.0 metadata —

digest/dependencies; checked 2026-07-23.

• PufferLib official docs — current 4.0 docs;

checked 2026-07-23.

• PufferLib source — default branch and

implementation; checked 2026-07-23.

• PufferTank 4.0 Dockerfile

— CUDA/Python reference; checked 2026-07-23.

• PufferLib 2.0 paper —

Reinforcement Learning Journal, 2025; use only for its stated benchmarks.

• PufferLib compatibility paper —

submitted 2024-06-18; describes an earlier API/performance profile.