# PyBevy: A Python Real-Time Engine Built on Bevy
[](https://discord.gg/hA4zUneA8f)
[](https://github.com/pybevy/pybevy#license)
[](https://pypi.org/project/pybevy/)
[](https://pypi.org/project/pybevy/)
```bash
$ pip install pybevy
```
> **Beta.** Python 3.12+. API evolving — breaking changes expected.
> Independently developed, community-maintained. Not affiliated with the Bevy project.
**[pybevy.com](https://pybevy.com)** — Project website & documentation
Write Python, save the file, and see your 3D scene update. Use NumPy, JAX, and PyTorch in the same process as a real 3D renderer. And when you want it, the AI can join the loop — it writes code, sees the result, and iterates.
- **Fast hot reload** — edit code, see changes near instantly, no restart, no recompile
- **Built on Bevy's renderer and ECS** — PBR, volumetric fog, cascaded shadows, bloom, SSAO
- **Python ecosystem in-process** — NumPy, JAX, PyTorch, Numba — just import
- **Optional AI feedback loop** — the AI writes Python, reloads, inspects the running scene, and iterates
- **If you know Bevy's Rust API**, PyBevy should feel immediately familiar
## Getting Started
### Installation
Pre-compiled wheels are available for the following platforms:
| Linux | x86_64 |
| macOS | ARM (Apple Silicon), x86_64 |
| Windows | x86_64 |
> **Browser sandbox** is in development — follow [#12](https://github.com/pybevy/pybevy/issues/12) for progress.
```bash
pip install pybevy --upgrade
```
#### Linux System Dependencies
PyBevy's pre-built wheels link against system display and audio libraries.
On most desktop distributions these are already present.
If you see an `ImportError` mentioning `libwayland-client.so` or `libasound.so`:
```bash
# Debian/Ubuntu
sudo apt install libwayland-client0 libasound2t64
# Fedora/RHEL
sudo dnf install alsa-lib wayland
```
**Docker / headless environments** also need a software GPU driver:
```bash
apt install -y libwayland-client0 libasound2t64 mesa-vulkan-drivers
```
ALSA warnings about missing audio devices are harmless and can be ignored.
### Free-Threaded Python (3.13t+)
PyBevy supports Python's free-threaded mode (PEP 703). Non-conflicting Python systems run truly in parallel on separate cores via Bevy's multi-threaded scheduler — no GIL serialization. Validated on CPython 3.14t. Performance depends on workload and scene complexity; see [Benchmarks](docs/benchmarks.md) for methodology and numbers.
> **Note:** The Numba JIT path (View API Tier 3) is not yet available on free-threaded Python — `llvmlite` does not ship 3.14t wheels yet. Tracked in [#8](https://github.com/pybevy/pybevy/issues/8).
## Quick Example
Parent-child entity hierarchy with a rotating parent cube. The child cube inherits the parent's transform automatically.
```python
from pybevy.decorators import component, entrypoint
from pybevy.prelude import *
@component
class Rotator(Component):
"""Marks entities that should rotate."""
def rotator_system(
time: Res[Time],
query: Query[Mut[Transform], With[Rotator]]
) -> None:
for transform in query:
transform.rotate_x(3.0 * time.delta_secs())
def setup(
commands: Commands,
meshes: ResMut[Assets[Mesh]],
materials: ResMut[Assets[StandardMaterial]],
) -> None:
cube_handle = meshes.add(Cuboid(2.0, 2.0, 2.0))
cube_material = materials.add(StandardMaterial(
base_color=Color.srgb(0.8, 0.7, 0.6)
))
# Parent cube — rotates
parent = commands.spawn(
Mesh3d(cube_handle),
MeshMaterial3d(cube_material),
Transform.from_xyz(0.0, 0.0, 1.0),
Rotator(),
)
# Child cube — follows the parent
parent.with_children(
lambda child: [
child.spawn(
Mesh3d(cube_handle),
MeshMaterial3d(cube_material),
Transform.from_xyz(0.0, 0.0, 3.0),
)
]
)
commands.spawn(PointLight(), Transform.from_xyz(4.0, 5.0, -4.0))
commands.spawn(
Camera3d(),
Transform.from_xyz(5.0, 10.0, 10.0).looking_at(Vec3.ZERO, Vec3.Y),
)
@entrypoint
def main(app: App) -> App:
return (
app.add_plugins(DefaultPlugins)
.add_systems(Startup, setup)
.add_systems(Update, rotator_system)
)
if __name__ == "__main__":
main().run()
```
Save this as `main.py` and run with hot reload:
```bash
pybevy watch --full main.py
```
Edit the code — the engine hot reloads near instantly, no restart, no recompile.
The `--full` flag reloads everything on each change, including setup systems. Without it, only Update systems are reloaded — faster for iterating on runtime behavior once your scene is set up.
### Native Plugin Approach (Rust + Python)
If you already have a Rust Bevy application, you can embed Python systems into it with `PyBevyPlugin`. Prototype in Python, ship critical paths in Rust.
> **Security:** `PyBevyPlugin` embeds a full CPython interpreter with unrestricted host access. Never execute untrusted Python code. We advise against using this for user-submitted plugin/modding systems without external sandboxing.
```rust
// main.rs - Your existing Rust Bevy application
use bevy::prelude::*;
use pybevy::PyBevyPlugin;
fn main() {
App::new()
.add_plugins(DefaultPlugins)
// Add Python systems from a module
.add_plugins(
PyBevyPlugin::new("game_logic")
.with_startup_system("setup")
.with_update_system("ai_behavior")
.with_hot_reload() // Edit Python, press F5 to reload!
)
// Mix with native Rust systems
.add_systems(Update, physics_step)
.run();
}
```
```python
# game_logic.py
from pybevy.prelude import *
ROTATION_SPEED = 1.0 # Change this and press F5!
def setup(commands: Commands) -> None:
commands.spawn(Transform.from_xyz(0.0, 0.0, 0.0))
def ai_behavior(query: Query[Mut[Transform]], time: Res[Time]) -> None:
for transform in query:
transform.rotation *= Quat.from_rotation_y(time.delta_secs() * ROTATION_SPEED)
```
See [docs/native-plugin.md](docs/native-plugin.md) for the full guide, including `#[derive(PyComponent)]` for exposing Rust components to Python and hot reload details.
### AI Feedback Loop
PyBevy includes a built-in [MCP server](https://modelcontextprotocol.io/) that lets AI agents write Python, reload the scene, capture screenshots, inspect entities, and iterate — automatically. The AI sees what it builds.
```bash
claude mcp add pybevy -- pybevy mcp # Claude Code
codex mcp add pybevy -- pybevy mcp # Codex
gemini mcp add pybevy -- pybevy mcp # Gemini CLI
```
Also works with Cursor and other MCP-compatible editors. See [docs/mcp.md](docs/mcp.md) for full setup.
## Bevy Compatibility
PyBevy versions target specific Bevy versions:
| 0.2.x | 0.18 |
| 0.1.x | 0.18 |
PyBevy follows Bevy's API conventions as closely as possible and targets full coverage of Bevy's public API. Core modules like transforms, lighting, cameras, and input are fully covered; others are in progress. See [API Coverage](docs/coverage.md) for current per-module stats and [Limitations](docs/limitations.md) for known constraints.
## Development Process
PyBevy started in May 2025 as a pure-Python ECS prototype, then moved through a
ctypes FFI layer before pivoting to PyO3, which became the real foundation.
Hand-written `.pyi` type stubs drove the API design before the Rust integration was
fully in place. The project also builds on Bevy experience going back to 2021.
The ECS query model, safety/validity system, and core Bevy component bindings were
developed manually across multiple iterations.
From November 2025 onward, AI tools were used more heavily for API coverage expansion
across Bevy's large surface area, crate splitting into ~30 feature crates, and parts
of the test/stub/documentation workflow.
To keep that process grounded, PyBevy is backed by a custom Rust API compliance tool
that validates bindings against Bevy's source and the Python stubs, and a test suite
spanning 100K+ lines. Both publishing soon.
## Limitations
- **No built-in physics** — use NumPy or JAX for physics computation, PyBevy for visualization.
- **Desktop only** — Linux, macOS, Windows. No mobile.
- **Code only** — no visual editor.
- **API is evolving** — see [Limitations](docs/limitations.md) for known constraints.
## Documentation
- **[pybevy.com](https://pybevy.com)** — Project website
- **[Examples](https://github.com/pybevy/pybevy/tree/main/examples)** — Runnable examples covering 2D, 3D, ECS, animation, and more
- **[API Coverage](docs/coverage.md)** — Per-module Bevy API coverage stats
- **[Limitations](docs/limitations.md)** — Known limitations
## Community & Contributing
- **Discord:** [Pybevy Discord](https://discord.gg/hA4zUneA8f) — questions, discussion, showcases
- **Contributing:** See [CONTRIBUTING.md](https://github.com/pybevy/pybevy/blob/main/CONTRIBUTING.md)
## License
All code in this repository is dual-licensed under either:
- [MIT License](https://github.com/pybevy/pybevy/blob/main/LICENSE-MIT)
- [Apache License 2.0](https://github.com/pybevy/pybevy/blob/main/LICENSE-APACHE)
at your option.
By contributing, you agree your work will be released under both licenses.
---
_When you want it, the world runs itself._