Godot Export & Builds (4.x)
Turn a project into runnable platform builds via export presets and the command line, and
handle the web/dedicated-server gotchas. Targets Godot 4.7.
When to use
- Use when producing a shippable build: installing export templates, creating/editing
export presets, exporting from the editor or headless CLI (CI), or troubleshooting web
(HTML5) and dedicated-server exports.
When not to use: storefront publishing flows → steam-publish/itch-publish; the
networking code of a server → godot-multiplayer (this skill covers building it headless).
Core workflow
- Install export templates matching your engine version: Editor menu >
Manage Export Templates (download), or install the
.tpz offline. Versions must
match the editor exactly. Since 4.7 the downloader can fetch templates for a single
platform or architecture instead of the full set.
- Add export presets in Project > Export: pick a platform (Windows Desktop, macOS,
Linux, Web, Android, iOS), set the export path, icons, features, and resource
include/exclude filters. Presets are saved to
export_presets.cfg.
- Export from the editor with Export Project (release) or Export PCK/ZIP.
- Or export headless from the CLI for automation/CI using
--export-release "<preset name>" <output path>.
- Per platform: Web needs cross-origin isolation (COOP/COEP) only if the preset's
Thread Support is on (off by default); Android needs the SDK/keystore; macOS/iOS need
signing for distribution.
- Smoke-test the build on the target before shipping — exported builds use
res://
read-only; write to user://.
Patterns
1. Headless CLI export (CI-friendly)
# Preset name must match exactly what's in Project > Export (quote it).
# Run from the project directory (where project.godot lives).
godot --headless --export-release "Windows Desktop" build/windows/game.exe
godot --headless --export-release "Linux" build/linux/game.x86_64
godot --headless --export-release "Web" build/web/index.html
# Debug build (includes debug symbols / remote debug):
godot --headless --export-debug "Windows Desktop" build/windows/game_debug.exe
# Export only the data pack (no executable):
godot --headless --export-pack "Linux" build/game.pck
# Export only files changed since the given base pack(s):
godot --headless --export-patch "Linux" build/patch1.pck --patches build/game.pck
2. Run a project headless (dedicated server / tests)
# No window/GPU — for a server build or automated runs.
godot --headless --path . res://server_main.tscn
# Quit after N main-loop iterations (frames, NOT seconds) — handy for a headless smoke test:
godot --headless --path . --quit-after 600
3. Detect the build context at runtime
func _ready() -> void:
if OS.has_feature("dedicated_server") or DisplayServer.get_name() == "headless":
_start_server_only() # skip rendering/UI on a headless server
if OS.has_feature("web"):
_apply_web_tweaks()
# Custom feature tags (added per preset) are also queryable:
# if OS.has_feature("demo"): limit_content()
4. Choose write paths that survive export
# res:// is READ-ONLY in exported games. Always write to user://.
func save_path() -> String:
return "user://savegame.tres" # resolves to the OS app-data dir
func _ready() -> void:
print(OS.get_user_data_dir()) # where user:// actually lives
Pitfalls
- "No export template found". Templates must match the exact editor version (incl.
beta/rc). Re-download via Manage Export Templates after upgrading Godot.
- Preset name mismatch in CLI.
--export-release "Windows" fails if the preset is
named "Windows Desktop". Names are case- and space-sensitive; quote them.
- Web build shows a blank page / threads error. Builds with the preset's Thread
Support option enabled require the server to send
Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp (cross-origin isolation for
SharedArrayBuffer). Must be served over HTTP(S), not opened as a file://. itch.io has
a "SharedArrayBuffer support" toggle for this. If the host cannot set headers (GitHub
Pages), leave Thread Support off — the default since 4.3.
- Writing to
res:// at runtime fails in exports (read-only, packed). Use user://.
- Missing resources in the build. Non-resource files (e.g. external
.json, .txt)
are not auto-included — add them via the preset's Resources > Filters to export
non-resource files (e.g. *.json).
- Android export needs setup: Android SDK/JDK paths in Editor Settings, a debug or
release keystore, and the
INTERNET permission for networked games.
- macOS/iOS distribution requires signing/notarization; unsigned macOS apps are
blocked by Gatekeeper.
- Debug vs release.
--export-debug enables remote debugging and debug checks; ship
--export-release.
References
- For the
export_presets.cfg structure, all useful CLI flags, custom feature tags,
PCK/expansion patching, encryption, and per-platform setup (Android keystore, macOS
signing, web headers), read references/presets-and-cli.md.
Related skills
godot-multiplayer — the dedicated-server code you export headless.
steam-publish / itch-publish — getting the build to players.
prototype-fast / game-jam — quick web/desktop builds for sharing.
1---2name: godot-export3description: >4 Export and build a Godot 4.7 project for distribution: install export templates,5 define export presets (Windows/macOS/Linux/Web/Android), run headless command-line6 exports for CI, and handle web (HTML5) COOP/COEP and dedicated-server/headless7 builds. Use when exporting a Godot game, configuring export_presets.cfg, building8 for web/desktop/mobile, or automating builds from the command line.9metadata:10 source: https://skillmd.com/skills/junmystery/godot-export11---1213# Godot Export & Builds (4.x)1415Turn a project into runnable platform builds via export presets and the command line, and16handle the web/dedicated-server gotchas. Targets **Godot 4.7**.1718## When to use1920- Use when producing a shippable build: installing export templates, creating/editing21 export presets, exporting from the editor or headless CLI (CI), or troubleshooting web22 (HTML5) and dedicated-server exports.2324**When *not* to use:** storefront publishing flows → `steam-publish`/`itch-publish`; the25networking code of a server → `godot-multiplayer` (this skill covers building it headless).2627## Core workflow28291. **Install export templates** matching your engine version: Editor menu >30 *Manage Export Templates* (download), or install the `.tpz` offline. Versions must31 match the editor exactly. Since 4.7 the downloader can fetch templates for a single32 platform or architecture instead of the full set.332. **Add export presets** in *Project > Export*: pick a platform (Windows Desktop, macOS,34 Linux, Web, Android, iOS), set the export path, icons, features, and resource35 include/exclude filters. Presets are saved to `export_presets.cfg`.363. **Export from the editor** with *Export Project* (release) or *Export PCK/ZIP*.374. **Or export headless from the CLI** for automation/CI using38 `--export-release "<preset name>" <output path>`.395. **Per platform:** Web needs cross-origin isolation (COOP/COEP) only if the preset's40 *Thread Support* is on (off by default); Android needs the SDK/keystore; macOS/iOS need41 signing for distribution.426. **Smoke-test the build** on the target before shipping — exported builds use `res://`43 read-only; write to `user://`.4445## Patterns4647### 1. Headless CLI export (CI-friendly)4849```bash50# Preset name must match exactly what's in Project > Export (quote it).51# Run from the project directory (where project.godot lives).52godot --headless --export-release "Windows Desktop" build/windows/game.exe53godot --headless --export-release "Linux" build/linux/game.x86_6454godot --headless --export-release "Web" build/web/index.html5556# Debug build (includes debug symbols / remote debug):57godot --headless --export-debug "Windows Desktop" build/windows/game_debug.exe5859# Export only the data pack (no executable):60godot --headless --export-pack "Linux" build/game.pck6162# Export only files changed since the given base pack(s):63godot --headless --export-patch "Linux" build/patch1.pck --patches build/game.pck64```6566### 2. Run a project headless (dedicated server / tests)6768```bash69# No window/GPU — for a server build or automated runs.70godot --headless --path . res://server_main.tscn71# Quit after N main-loop iterations (frames, NOT seconds) — handy for a headless smoke test:72godot --headless --path . --quit-after 60073```7475### 3. Detect the build context at runtime7677```gdscript78func _ready() -> void:79 if OS.has_feature("dedicated_server") or DisplayServer.get_name() == "headless":80 _start_server_only() # skip rendering/UI on a headless server81 if OS.has_feature("web"):82 _apply_web_tweaks()83 # Custom feature tags (added per preset) are also queryable:84 # if OS.has_feature("demo"): limit_content()85```8687### 4. Choose write paths that survive export8889```gdscript90# res:// is READ-ONLY in exported games. Always write to user://.91func save_path() -> String:92 return "user://savegame.tres" # resolves to the OS app-data dir9394func _ready() -> void:95 print(OS.get_user_data_dir()) # where user:// actually lives96```9798## Pitfalls99100- **"No export template found".** Templates must match the exact editor version (incl.101 beta/rc). Re-download via *Manage Export Templates* after upgrading Godot.102- **Preset name mismatch in CLI.** `--export-release "Windows"` fails if the preset is103 named `"Windows Desktop"`. Names are case- and space-sensitive; quote them.104- **Web build shows a blank page / threads error.** Builds with the preset's *Thread105 Support* option enabled require the server to send106 `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp` (cross-origin isolation for107 `SharedArrayBuffer`). Must be served over HTTP(S), not opened as a `file://`. itch.io has108 a "SharedArrayBuffer support" toggle for this. If the host cannot set headers (GitHub109 Pages), leave *Thread Support* off — the default since 4.3.110- **Writing to `res://` at runtime fails** in exports (read-only, packed). Use `user://`.111- **Missing resources in the build.** Non-resource files (e.g. external `.json`, `.txt`)112 are not auto-included — add them via the preset's *Resources > Filters to export113 non-resource files* (e.g. `*.json`).114- **Android export needs setup**: Android SDK/JDK paths in Editor Settings, a debug or115 release **keystore**, and the `INTERNET` permission for networked games.116- **macOS/iOS distribution requires signing/notarization**; unsigned macOS apps are117 blocked by Gatekeeper.118- **Debug vs release.** `--export-debug` enables remote debugging and debug checks; ship119 `--export-release`.120121## References122123- For the `export_presets.cfg` structure, all useful CLI flags, custom feature tags,124 PCK/expansion patching, encryption, and per-platform setup (Android keystore, macOS125 signing, web headers), read `references/presets-and-cli.md`.126127## Related skills128129- `godot-multiplayer` — the dedicated-server code you export headless.130- `steam-publish` / `itch-publish` — getting the build to players.131- `prototype-fast` / `game-jam` — quick web/desktop builds for sharing.