Installation¶
Requirements¶
- Python 3.12 or newer
- NumPy ≥ 2.0, SciPy ≥ 1.12, JAX[cpu] ≥ 0.4.25
- moderngl ≥ 5.10, glfw ≥ 2.5, Pillow ≥ 10.0, imageio ≥ 2.34 (rendering)
- gymnasium ≥ 0.29, stable-baselines3 ≥ 2.2, optax ≥ 0.2, matplotlib ≥ 3.8 (RL)
forge3d runs entirely on CPU — no CUDA, no GPU required for physics or training.
pip (recommended)¶
# Full install — physics, rendering, and RL in one command
pip install pyforge3d
# WebGPU renderer (experimental, P34 — falls back to OpenGL if omitted)
pip install "pyforge3d[experimental]"
Package name vs import name
The PyPI distribution is named pyforge3d, but the import is always:
Optional extras¶
| Extra | Packages installed | Needed for |
|---|---|---|
experimental |
wgpu, rendercanvas | WebGPU renderer (P34, falls back to OpenGL) |
dev |
pytest, ruff, mypy | Development and testing |
docs |
mkdocs-material, mkdocstrings | Building this documentation |
all |
experimental + dev + docs | Everything |
Headless / server environments¶
The realtime renderer uses Xvfb + Mesa llvmpipe (software OpenGL) on headless servers. forge3d detects the environment and starts Xvfb automatically if needed.
# Install system deps (Ubuntu / Debian)
sudo apt-get install xvfb libgl1-mesa-glx libglib2.0-0
# Or run with an explicit virtual display
export DISPLAY=:99
Xvfb :99 -screen 0 1280x720x24 &
python my_script.py
The HQ ray-tracer has no display dependency — it writes PNG/MP4 directly.
Development install¶
git clone https://github.com/iruki-dev/forge3d.git
cd forge3d
pip install -e ".[dev]"
# Run test suite
pytest tests/ -q
# Lint + type-check
ruff check src/ && mypy src/
Optional Rust core¶
The Rust extension (forge3d._core) accelerates the PGS contact solver, GJK/EPA,
and BVH broadphase. It is optional — forge3d falls back to pure Python automatically.
pip install maturin
maturin develop # development build
cargo test --workspace # run Rust tests
# Check whether the extension loaded
python -c "from forge3d.backend import USE_RUST_CORE; print('Rust core:', USE_RUST_CORE)"