godot-ci/docs/research/godot-musl-alpine.md

Do official Godot Linux binaries run on Alpine/musl?

Research date: 2026-08-06. Scope: official binaries from downloads.tuxfamily.org / github.com/godotengine/godot-builds (the same source abarichello/godot-ci downloads from) — not self-compiled or third-party (e.g. Alpine's own package) builds.

VERDICT

(a) Editor binary (headless export, godot --headless --export-release ...) Works with gcompat at best, unverified/likely-partial — more precisely: Does not work out of the box; requires gcompat, and even gcompat is not confirmed sufficient.

• The official Linux editor/export-template binaries are built in a Fedora-based container and dynamically linked against glibc 2.34 (see Sources: godotengine/build-containers). They are not static and not musl-native.
• Godot's own source will not even compile on musl without patches (undefined backtrace/backtrace_symbols, PTHREAD_MUTEX_RECURSIVE_NP, isnanf differences) — this doesn't affect running a prebuilt glibc binary directly, but it confirms the codebase has known musl-specific assumptions that could also bite at runtime.
• Multiple Godot maintainers/contributors state plainly: "Godot currently only runs on Linux distributions with glibc as libc implementation. On distros with musl libc, it won't compile." (godot-proposals#2439). No official statement confirms gcompat works for the editor.
• A related, unresolved report (godot/godot#21282) describes the Godot editor segfaulting on launch on musl-libc distros (Alpine, Gentoo), with the reporter speculating about musl stack-size differences. It was closed/archived as stale, not fixed — so the risk of a crash isn't hypothetical, it has a filed report, even though the report predates gcompat's now-common usage and doesn't test it explicitly.
• No GitHub issue, forum post, or doc page found in this research confirms someone successfully ran the official headless editor via gcompat for exports. Community Docker images for headless Godot CI (e.g. robpc/docker-godot-headless, barichello/godot-ci itself) are all Debian/Ubuntu-based, not Alpine — which is itself weak circumstantial evidence that the ecosystem defaults to glibc bases rather than having solved this on Alpine.

(b) Do export templates care about the host libc? No — the concern is purely about the editor binary, not the templates.

• Export templates are per-target-platform binaries/build artifacts (Windows .exe, macOS .app, Android .apk components, Linux .x86_64, etc.) that the editor copies/embeds into the exported project. The editor process doing the exporting does not execute the Linux export template as a subprocess as part of a normal export — it reads/writes template files and packs the PCK. The host libc constrains only whether the editor binary itself can run on the CI host; it has no bearing on which libc the exported game (or its Linux export template) targets. That's a separate, independent concern for whoever runs the exported game later.
• Caveat: this reasoning is architectural inference from how the export pipeline works, not from an explicit Godot doc sentence that says "host libc does not affect templates" — no such explicit statement was found in docs.godotengine.org. Treat sub-question (b)'s verdict as high-confidence but not directly quoted from an official source.

Static / musl-native build question

No official static or musl-native Linux build exists.

• A GitHub Discussion on quaadgras/graphics.gd (a Godot GDExtension/Go binding project) states directly: "The Godot Foundation doesn't provide official musl builds." The same discussion explains why a static musl build is hard even in principle: Godot needs dlopen at runtime to load X11/Wayland/OpenGL/Vulkan drivers, and musl refuses to implement dlopen for statically-linked binaries (by design, to avoid loading glibc-ABI shared objects into a musl process). The project's workaround is a hand-written assembly TLS trampoline, not something Godot upstream does.
• Separately, godot/godot#111876 shows even Godot's static library build mode (LibGodot) is currently broken/unsupported on Linux, for unrelated build-system reasons — reinforcing that "just statically link it" is not a solved path upstream.
• Alpine Linux itself packages a musl-native godot build compiled from source (pkgs.alpinelinux.org, package godot version 4.6-r2, in the edge/testing repo, linked against so:libc.musl-x86.so.1). This is a real, working musl-native Godot editor — but it is an Alpine/community-maintained rebuild from source, not the official Godot Foundation binary, is in the testing repo (not stable/main), and its version lag/coverage relative to the official releases used by godot-ci was not verified.
• Godot's own compiling-for-Linux docs list Alpine apk build dependencies (implying compiling from source on Alpine is a supported, documented path — see Sources), which is consistent with "build your own musl-native binary" being viable, while "run the official prebuilt binary on musl" is not.

Sub-question 1 detail — editor binary and host libc

• Build environment: godotengine/build-containers README states the Linux build container's base image is Fedora 44, and its Linux SDK toolchain is "GCC 15.2.0 built against glibc 2.34, binutils 2.46.0." This is the container that produces the official editor/export-template binaries godot-ci and this repo download. Fedora and its glibc toolchain confirm the binaries are dynamically linked against glibc, not statically linked and not musl.
• Compiling docs list Alpine packages, but for source builds only: docs.godotengine.org's "Compiling for Linux, *BSD" page lists an Alpine apk add package list (scons pkgconf gcc g++ libx11-dev ...) for people who want to compile Godot themselves on Alpine. It does not discuss musl vs glibc, gcompat, or static linking, and it does not say the official prebuilt binaries work on Alpine. A companion doc bug (godotengine/godot-docs#9180, filed 2024-04-03, still open in this research) flags that the Alpine package list is stale (libexecinfo-dev removed from Alpine since 3.17) and that musl builds should instead pass execinfo=no to SCons — again, this is guidance for compiling from source on Alpine, not for running the official downloaded binary.
• Known runtime failure report: godot/godot#21282, "Segmentation fault on opening a project on musl libc" — reproduced on Gentoo and Alpine, editor crashes immediately when opening a project. Root cause undetermined by the reporter ("might be ... musl stack size"); issue closed/archived without resolution. This predates widespread gcompat adoption and doesn't test it, so it neither confirms nor rules out gcompat as a fix — but it is documented evidence that musl-adjacent environments have triggered editor crashes.
• Compile-time musl blockers (indirect evidence of glibc coupling):
  • godot/godot#63978 — Alpine 3.16 compile fails: undefined references to backtrace/backtrace_symbols (musl's execinfo.h handling differs from glibc's). Closed as "not planned."
  • godot/godot#31555 — VHACD third-party module fails to compile on musl due to PTHREAD_MUTEX_RECURSIVE_NP, a glibc-specific macro.
  • godot/godot-proposals#2439 — proposal to #ifdef __GLIBC__-guard glibc-specific code and support musl properly; states plainly Godot "currently only runs on Linux distributions with glibc." Closed, linked to PR #63983 (partial follow-up on the basename difference, not full musl support).
  • godot/godot#20037 — long-running "[TRACKER] musl libc support in Godot," opened by someone building an Alpine-based Godot Docker image, covering execinfo.h, isnanf vs isnan, and the segfault above. Closed without musl becoming an official target.
• gcompat's actual capability: Alpine's gcompat package/mirror (Stantheman/gcompat on GitHub, description corroborated via search results; the canonical wiki.alpinelinux.org/wiki/Running_glibc_programs page returned HTTP 403 to automated fetch in this research and could not be quoted directly) is described consistently across secondary sources as: a small compatibility shim providing glibc-ABI-compatible symbols and dynamic-linker paths so some glibc-linked binaries run on musl — explicitly not a full glibc reimplementation, and known to fail for more complex binaries (a commonly cited example in search results: Godot-Jolt, a Godot GDExtension, reportedly does not work on Alpine even with gcompat or alpine-pkg-glibc installed — secondary evidence, a search-result summary rather than a page this research fetched and quoted directly). This is consistent with an engine-sized C++ binary like the Godot editor being a poor gcompat candidate, but there is no first-party confirmation either way for the Godot editor specifically.

Sub-question 2 detail — export templates and libc

• Godot's Linux export docs (docs.godotengine.org/en/stable/tutorials/export/exporting_for_linux.html) discuss export architecture options (x86_64/x86_32/arm) but say nothing about host libc or export-template libc requirements — no relevant text found on that page in this research.
• By Godot's export architecture: the editor process reads template binaries (downloaded/bundled per target platform) and assembles the exported project; it does not need to execute a Linux export template as part of exporting to Linux (self-hosted export execution isn't part of the pipeline the way, say, code-signing tools might be for other platforms). This means:
  • The editor's ability to run on the CI host is gated by the host's libc (glibc vs musl+gcompat), per sub-question 1.
  • The export templates' relevant libc/ABI concerns are about the target platform the exported game will run on later (e.g. does the Linux export template embedded into the exported game work on the end-user's glibc or musl system) — a wholly separate question from whether the CI host running the editor is Alpine or Debian.
  • No official doc text was found stating this explicitly; it is inferred from the documented shape of the export pipeline rather than a quoted source, so treat with the caveat noted in the VERDICT section.

Sources

URL	What it established
https://github.com/godotengine/build-containers	Official Linux build container base image is Fedora 44, toolchain built against glibc 2.34 — official binaries are glibc-linked, not static/musl. (README fetched via WebFetch)
https://github.com/godotengine/godot-proposals/issues/2439	Explicit maintainer/contributor statement: "Godot currently only runs on Linux distributions with glibc... On distros with musl libc, it won't compile." Proposal to add __GLIBC__ guards; closed, partially addressed by PR #63983.
https://github.com/godotengine/godot/issues/20037	Long-running musl-support tracker opened by an Alpine-Docker-image author; covers execinfo.h, isnanf/isnan, segfaults; closed without musl becoming an official target.
https://github.com/godotengine/godot/issues/21282	Reported editor segfault on project-open specifically on musl (Alpine, Gentoo); root cause undetermined; closed/archived unresolved.
https://github.com/godotengine/godot/issues/63978	Alpine 3.16 compile failure: undefined backtrace/backtrace_symbols due to musl's execinfo handling; closed "not planned."
https://github.com/godotengine/godot/issues/31555	VHACD third-party module uses glibc-specific PTHREAD_MUTEX_RECURSIVE_NP, breaking musl compiles.
https://github.com/godotengine/godot/issues/111876	Godot's static-library (LibGodot) build mode is currently broken on Linux — static linking isn't a solved path upstream even outside the musl question.
https://github.com/godotengine/godot-docs/issues/9180	Docs bug: Alpine apk package list in the compiling guide is stale (libexecinfo-dev gone since Alpine 3.17); recommends execinfo=no for musl source builds. Still open at research time.
https://docs.godotengine.org/en/4.4/contributing/development/compiling/compiling_for_linuxbsd.html	Official compiling-for-Linux doc; lists an Alpine apk add package list for source builds; does not mention musl, glibc, gcompat, or static linking explicitly.
https://docs.godotengine.org/en/stable/tutorials/export/exporting_for_linux.html	Official Linux export doc; covers export architecture options; contains no host-libc or template-libc guidance either way.
https://github.com/quaadgras/graphics.gd/discussions/242	Direct statement "The Godot Foundation doesn't provide official musl builds"; explains musl's dlopen-refusal-on-static-binaries as the core technical obstacle to a static/musl-native Godot; describes a custom TLS-trampoline workaround used by that (unrelated, third-party) project — not something Godot upstream ships.
https://pkgs.alpinelinux.org/package/edge/testing/x86/godot	Confirms Alpine ships its own musl-native godot package (v4.6-r2, edge/testing repo, linked against so:libc.musl-x86.so.1) — a real musl-native build, but Alpine/community-maintained, not the official Godot Foundation binary, and in the testing (not stable) repo.
https://github.com/godotengine/godot-build-scripts	Confirms official release build scripts use containers from godotengine/build-containers; did not itself surface Dockerfile content (fetch returned only the repo overview).
G:_DEV\repos\godot-ci\Dockerfile (this repo, local file)	Confirms this repo's current image is built FROM barichello/godot-ci:${GODOT_VERSION} using apt-get (Debian/Ubuntu-based, glibc) — i.e., the status quo this research is evaluating an Alpine alternative against.

Secondary evidence only (not proof, not fetched/quoted directly — flagged per task instructions)

• Search-result summaries (not independently fetched and verified page-by-page in this research) reported: a Godot Jolt GDExtension addon reportedly does not work on Alpine even with gcompat or alpine-pkg-glibc installed. Cited as a data point that gcompat compatibility for glibc-linked Godot-adjacent binaries is inconsistent, not as proof about the core editor binary.
• wiki.alpinelinux.org/wiki/Running_glibc_programs returned HTTP 403 to this research's fetch tool and could not be quoted directly; gcompat's description above is reconstructed from consistent secondary summaries (Medium post, Alpine aports mirror descriptions, HN discussion) rather than the primary wiki text itself. Treat the general characterization of gcompat as reliable (it matches gcompat's well-known public description) but not as a verbatim-cited primary source in this research.
• aronand/godot-alpine (GitHub repo, "Godot on Alpine Linux") appeared in search results as a potentially relevant project but was not fetched/read in this research; flagging its existence only, not its content, as an unverified pointer for follow-up.
• godotforums.org thread "Help with exporting games for alpine and musl based systems" — returned only a loading-error page to this research's fetch tool; could not be summarized or cited despite being a promising-looking thread title. Flagging as an unresolved follow-up, not evidence.

Bottom line for godot-ci's purposes

Given the official Linux editor is a glibc 2.34 binary from a Fedora-based build container, and there is no official statement or found report of successfully running it under Alpine+gcompat for headless exports (only an unresolved musl-segfault report and general "gcompat doesn't fix everything" signals), switching this repo's base image to Alpine is not a low-risk change without first prototyping it end-to-end (pull the real downloads.tuxfamily.org editor zip, apk add gcompat, and run a real --headless --export-release in a throwaway Alpine container) to see whether it actually works, rather than assuming gcompat is sufficient. Export templates themselves are not a blocker for this decision either way.