Getting started

This page covers building Bevy from a fresh checkout of bevyengine/bevy. If you just want to use Bevy in your own project, follow the official Quick Start Guide instead — it covers cargo new workflows that are out of scope here.

Prerequisites

• Rust toolchain. Bevy's MSRV is declared in the workspace Cargo.toml (rust-version = "1.95.0" at the time of writing). Install via rustup. The repo pins no toolchain file, so stable is fine.
• A C/C++ toolchain. Required by some native dependencies (audio, image codecs).
• Linux only: install the development packages listed in docs/linux_dependencies.md. On Debian/Ubuntu that's roughly libasound2-dev libudev-dev libwayland-dev libxkbcommon-dev.
• macOS only: Xcode command-line tools (xcode-select --install).
• Windows only: the MSVC build tools (the rustup installer prompts you).
• Optional: cargo-watch, lld/mold for faster incremental linking, wasm-pack or wasm-bindgen-cli for browser examples (see tools/build-wasm-example).

Cloning and building

git clone https://github.com/bevyengine/bevy
cd bevy

# A first build is slow (cold compile of ~150 dependencies).
# Use --release for representative performance numbers.
cargo build --release

The first build takes 5–15 minutes depending on your machine. Subsequent incremental builds are much faster — see "Fast compiles" below.

Running examples

Examples live under examples/. Each *.rs file at the leaf level is a runnable target listed in the workspace Cargo.toml under [[example]] entries.

# 2D
cargo run --example breakout

# 3D
cargo run --example 3d_scene

# UI
cargo run --example ui

# A specific topic
cargo run --example animated_material

For a full list, browse examples/README.md (it's auto-generated by tools/build-templated-pages from the [[example]] metadata in the root Cargo.toml).

Examples that need extra features

Some examples require non-default features. The error message tells you which:

# Bevy Remote Protocol example
cargo run --example remote_server --features="bevy_remote"

# Solari (experimental ray-traced lighting)
cargo run --example solari --features="bevy_solari"

Web examples

The examples/wasm/ directory and tools/build-wasm-example contain helpers to run examples in a browser via WebGPU/WebGL2:

# Build a wasm version of an example
cargo run -p build-wasm-example -- breakout

# Then serve the output directory with any static file server

Mobile examples

examples/mobile/ is a separate cargo crate that builds for Android and iOS. See its README.md for the (fairly involved) setup.

Workspace tasks

Bevy uses a custom CI script in tools/ci/ that runs all workspace checks. It's the canonical way to reproduce CI locally:

# Run everything (lint, format, tests, doctests, examples)
cargo run -p ci -- check

# Run a specific task: lints
cargo run -p ci -- lints

# Just the tests
cargo run -p ci -- test

# Format check
cargo run -p ci -- format

# Just compile-time checks (no run)
cargo run -p ci -- compile

tools/ci/src/main.rs lists every task. Most map to the obvious cargo command (cargo clippy, cargo test, cargo fmt --check).

Fast compiles

Bevy's "fast compiles" recipe uses LLD or mold and the cranelift backend. The repository's .cargo/ directory ships a pre-tuned config:

• .cargo/config_fast_builds.toml — sets the linker to lld or mold per platform and turns on shared generics. Copy to .cargo/config.toml to opt in.
• The dynamic_linking cargo feature compiles bevy_dylib as a .so/.dylib/.dll so you don't relink the whole engine on every change.

Typical workflow:

cargo run --features dynamic_linking --example 3d_scene

Full setup is documented at https://bevy.org/learn/quick-start/getting-started/setup.

Tests

# All workspace tests
cargo test --workspace

# A specific crate
cargo test -p bevy_ecs

# UI / "compile fail" tests (uses the trybuild harness)
cargo test -p bevy_derive --test compile_fail
cargo test -p bevy_ecs --test compile_fail
cargo test -p bevy_reflect --test compile_fail

Compile-fail tests verify that derive macros emit the right error messages when given bad input. They live under crates/<crate>/compile_fail/.

Docs

# Build the rustdoc for the whole workspace, with links between crates
cargo doc --no-deps --workspace --open

The docs-rs/ and docs-template/ directories contain hand-tuned docs.rs configuration; you don't normally touch them.

Editor integration

Bevy is plain Rust, so any Rust editor works. The community uses VS Code with rust-analyzer most often. The repo ships a .vscode/settings.json (under tools/) with sensible defaults for working with the workspace.

For a printable cheat sheet on debugger setup, profiling, and tracing see docs/debugging.md and docs/profiling.md. Once you have the wiki open you can also look at How to contribute → debugging.

Where to go next

• Read the architecture page to build a mental model.
• Read the glossary to learn Bevy-specific vocabulary.
• Pick a crate from Packages and skim its index page.