Getting started

This page covers compiling Godot from source, running the editor, and running the unit test suite. The official documentation at https://docs.godotengine.org/en/latest/contributing/development/compiling is the authoritative reference; what follows summarizes what you need locally to be productive in this repo.

Prerequisites

Platform	Compiler	Toolchain
Linux/BSD	GCC ≥ 9 or Clang ≥ 7	pkg-config, X11/Wayland headers, ALSA/PulseAudio
Windows	MSVC ≥ 2019 (preferred) or MinGW	Windows 10 SDK
macOS	Apple Clang	Xcode 14+
Android	NDK r23c+	Java 17, gradle
iOS / visionOS	Xcode 14+	only on macOS
Web	Emscripten 3.1.62+	for target=web builds

All targets need:

• Python 3.8+ (the build system, pre-commit hooks, and class reference tools are Python).
• SCons 4.x (pip install scons).
• Git (for submoduleless thirdparty layout — third-party code is vendored under thirdparty/, not via submodules).

pyproject.toml documents the Python tooling Godot uses for itself: ruff (lint + format), mypy (type-check), and the pre-commit hooks defined in .pre-commit-config.yaml.

Cloning

git clone https://github.com/godotengine/godot.git
cd godot

The repo is large (~83k commits, ~1700 .cpp files outside thirdparty/). A shallow clone is fine for a single build but limits git blame and PR work; prefer a full clone when contributing.

First build

The default target is the editor for the current platform.

# Linux/BSD
scons platform=linuxbsd target=editor

# Windows (in a Visual Studio Developer Command Prompt)
scons platform=windows target=editor

# macOS
scons platform=macos target=editor arch=arm64    # or arch=x86_64

Resulting binaries are placed in bin/. They are named after the build:

• Editor: bin/godot.<platform>.editor.<arch> (e.g., godot.linuxbsd.editor.x86_64)
• Debug template: target=template_debug
• Release template: target=template_release

Useful flags:

Flag	Purpose
dev_build=yes	Debug symbols, asserts, fast incremental builds
dev_mode=yes	Like dev_build=yes plus extra warnings as errors
optimize=size / optimize=speed / optimize=debug	Override target defaults
use_lto=auto	Link-time optimization
module_<name>_enabled=no	Disable a module (see modules/<name>/config.py)
tests=yes	Compile the doctest unit tests
production=yes	Sets the flags expected for official release builds
scu_build=yes	Single-compilation-unit mode for faster compile + smaller objects
compiledb=yes	Emit compile_commands.json for clangd/IDE integration
verbose=yes	Print full compile commands
-j$(nproc)	Parallel jobs (SCons accepts -j like make)

For an interactive list of options:

scons --help

Running

The editor binary is also the project manager binary. With no arguments, it opens the project manager. With --editor /path/to/project.godot, it opens that project. With --path /path/to/project, it runs the project (no editor).

# Open the project manager
./bin/godot.linuxbsd.editor.x86_64

# Run the doctest suite
./bin/godot.linuxbsd.editor.x86_64 --headless --test

Useful CLI flags (parsed in main/main.cpp):

Flag	Purpose
--editor (-e)	Force editor mode
--project-manager (-p)	Force project manager
--path <dir>	Set working project directory
--main-pack <pck>	Run an exported PCK file
--rendering-driver <vulkan|d3d12|metal|opengl3|opengl3_es|dummy>	Pick a backend
--display-driver <name>	Override display server (e.g., wayland, x11, headless)
--audio-driver <name>	Override audio backend
--remote-debug <host:port>	Connect to a debug server
--script <path>	Run a .gd/.cs script with no scene
--headless	No window, no audio — useful for CI
--quit	Run one frame and exit (for screenshots, baking)
--verbose	Verbose engine logging
--dump-extension-api	Emit extension_api.json (used by GDExtension consumers)

Building specific targets

# Mono / C# editor build (requires .NET 8 SDK on PATH)
scons platform=linuxbsd target=editor module_mono_enabled=yes

# After the first Mono build, generate the C# glue:
./bin/godot.linuxbsd.editor.x86_64 --headless --generate-mono-glue modules/mono/glue
scons platform=linuxbsd target=editor module_mono_enabled=yes build_assemblies=yes

# Android editor / templates
scons platform=android target=editor arch=arm64 generate_android_apk=yes
cd platform/android/java && ./gradlew generateGodotEditor

# Web template
scons platform=web target=template_release threads=yes

See platform/<name>/SCsub and platform/<name>/detect.py for per-platform options.

Running tests

The unit tests use doctest, with the harness in tests/test_main.cpp.

scons platform=linuxbsd target=editor tests=yes
./bin/godot.linuxbsd.editor.x86_64 --headless --test                  # all tests
./bin/godot.linuxbsd.editor.x86_64 --headless --test --test-case='*Vector3*'
./bin/godot.linuxbsd.editor.x86_64 --headless --test --help           # doctest help

Test sources live alongside what they test, ending in .test.h or under tests/. See Testing.

Linting and formatting

Pre-commit hooks are defined in .pre-commit-config.yaml. Install them once:

pip install pre-commit
pre-commit install

The hooks run:

• clang-format for C++ (config: .clang-format)
• clang-tidy for C++ (config: .clang-tidy)
• ruff for Python lint and format
• mypy for Python type-checking
• Black-style formatting for .cs C# files
• A custom hook to verify XML class reference docs match the bound API

Run all hooks against the working tree:

pre-commit run --all-files

Editor for the editor

For comfortable C++ work, generate compile_commands.json and point your IDE at it:

scons compiledb=yes platform=linuxbsd target=editor dev_build=yes

.clangd in the repo root configures clangd to use this database and to apply the project's include/define conventions.

Common pitfalls

• Out-of-tree builds are not supported. SCons writes object files into per-platform bin/obj/ subdirectories.
• Mixing dev_build=yes and production=yes is not supported; pick one.
• Mono builds require two passes — once to produce the binary, once to generate and reference C# glue. The README in modules/mono/README.md walks through this.
• Windows builds with MinGW require use_mingw=yes because MSVC is the default. Ditto for use_llvm=yes to switch to clang.
• Editor + export templates need separate builds. The exporter relies on already-compiled templates living under ~/.local/share/godot/export_templates/<version>/ (or platform equivalent).