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

Does official Blender run under Alpine/musl?

Research for wayfinder ticket #5. Scope: this repo currently downloads the official glibc Linux tarball from download.blender.org/release/ (see Dockerfile, scripts/resolve-blender-url.sh) onto a barichello/godot-ci (Ubuntu/glibc) base, and uses it for headless .blend → asset import in the Godot CI pipeline. This doc asks whether that same tarball, or any Blender build, works on an Alpine/musl base.

Verdict

• Official tarball on Alpine as-is: does not work. It is a glibc build (Blender requires glibc ≥ 2.28 per Blender's own requirements page) and Alpine ships musl instead of glibc, with no glibc present at all.
• Official tarball via gcompat: unproven / likely does not work reliably. gcompat is explicitly a shim for pre-built glibc binaries and is documented by Alpine as not fully compatible — "some [binaries] will still not work with this patch." The one concrete community attempt found (a PR against ikester/blender-docker) tried exactly this — official binary + Alpine + presumably gcompat/manual lib shims — and failed with missing libraries (libGLU.so.1, libXrender.so.1) and unresolved glibc-only symbols (__sched_cpualloc, qsort_r, backtrace). The image never ran. This is a single secondary data point, not exhaustive, but it's the only real-world attempt this research turned up and it failed outright.
• musl-native alternative exists: yes. Alpine's community repository packages Blender from source against musl — blender, blender-headless, blender-shared, blender-doc, py3-blender — currently at 5.2.0-r0 for x86_64. blender-headless is specifically the no-GUI server/CLI build, i.e. exactly the shape needed for a Godot import pipeline (blender --background --python ...).
• Caveat on the alternative: as of this research, the Alpine package index shows these packages only in the edge branch, not in a released stable branch (e.g. v3.20/v3.21). Edge is Alpine's rolling/ unstable branch — usable, but it means pinning to a moving target rather than a versioned stable release, which cuts against the reproducibility this pipeline wants from a pinned Blender version.
• Headless .blend import specifically: not separately verified beyond the existence of blender-headless and its description ("headless build" for server/automation use). No primary Blender-side documentation or Alpine changelog was found confirming Python-scripted --background import/export works flawlessly on the musl build; this is inferred from the package's stated purpose, not confirmed by a run.

Net: there is a plausible musl-native path (Alpine community/edge blender-headless), but it is edge-only today, and the "just run the official tarball via gcompat" path has a real failure report against it. Either the pipeline pins to Alpine edge (accepting rolling-release churn) or Alpine is not a good fit for this image's need for a stable, pinned Blender version.

Details and sources

Official Blender's own requirement (primary)

Blender's official download requirements page (blender.org) states Linux support requires glibc 2.28 or newer; for older glibc (e.g. glibc 2.17 / RHEL 7) Blender recommends staying on the old Blender 3.4 release instead. This is a hard glibc dependency stated by Blender itself — nothing on that page mentions musl or Alpine as a supported target. (https://www.blender.org/download/requirements/, https://www.blender.org/download/)

Blender's Linux build documentation (https://developer.blender.org/docs/handbook/building_blender/linux/) returned HTTP 403 to automated fetch during this research and could not be quoted directly; it is generally understood (and consistent with the glibc requirement above) to target mainstream glibc distros for both building and running Blender, with no documented musl/Alpine build target.

Alpine's gcompat (primary — Alpine wiki/GitHub)

• Alpine's own wiki page on running glibc programs (https://wiki.alpinelinux.org/wiki/Running_glibc_programs) describes gcompat as the mechanism for running already-compiled glibc binaries on musl by intercepting the glibc dynamic linker path and redirecting to musl plus a set of compatibility shims. (Fetched via search-engine summary — the wiki itself returned HTTP 403 to direct fetch during this research.)
• The gcompat project itself (https://github.com/rs--/gcompat, mirrored at https://github.com/Stantheman/gcompat) states plainly: it works for binaries already compiled against glibc, has no headers, and cannot be used to build software that requires glibc. It explicitly warns that "some [glibc binaries] will still not work with this patch," and recommends fixing/porting software to be libc-portable instead of relying on gcompat for anything beyond simple/small binaries.
• Alpine's gcompat package on pkgs.alpinelinux.org is present in the main repo, version 1.1.0-r4 (checked build date 2023-07-31) — small and simple, consistent with its stated scope (a shim, not a glibc reimplementation). (https://pkgs.alpinelinux.org/packages?name=gcompat)

Blender is a large, complex application (OpenGL/Vulkan, audio via PulseAudio/PipeWire, X11, dozens of bundled C/C++ libraries, a bundled Python). This is exactly the profile gcompat's own documentation flags as likely to fail — and the one concrete attempt found (below) did fail.

Alpine's musl-native Blender package (primary — pkgs.alpinelinux.org)

pkgs.alpinelinux.org package index, checked directly:

package	branch	repo	arch	version	purpose
blender	edge	community	x86_64	5.2.0-r0	full GUI build
blender-headless	edge	community	x86_64	5.2.0-r0	no-GUI build for server/automation
blender-shared	edge	community	x86_64	5.2.0-r0	shared libs subpackage
blender-doc	edge	community	x86_64	5.2.0-r0	docs
py3-blender	edge	community	x86_64	5.2.0-r0	Python bindings subpackage

(https://pkgs.alpinelinux.org/package/edge/community/x86_64/blender, https://pkgs.alpinelinux.org/package/edge/community/x86_64/blender-headless)

Since Alpine's community/main repos are built from source (aports) against musl, these are native musl builds, not the glibc tarball run through a shim — this is the actual "musl-friendly alternative" the ticket asks about. blender-headless's description ("headless build", no GUI deps) matches the "background import for a CI asset pipeline" use case directly.

The important caveat, also confirmed directly against the package index: these packages appear to exist only under the edge branch at the time of this research (no stable-branch listing, e.g. v3.20/v3.21, was found for blender/blender-headless). Alpine's edge is the rolling development branch — using it means tracking a moving target rather than a pinned stable Alpine release, which works against the kind of reproducible, version-pinned build this repo's resolve-blender-url.sh / resolve-godot-version.sh scripts are designed around.

Community corroboration (secondary)

• ikester/blender-docker PR #1 ("Change to use alpine linux, much smaller base image size", https://github.com/ikester/blender-docker/pull/1): contributor tried moving that Dockerfile to Alpine using the official Blender binary. Result reported by the repo owner: it did not run — missing libGLU.so.1, libXrender.so.1, and unresolved glibc-only symbols (__sched_cpualloc, qsort_r, backtrace). The owner asked the contributor to "sort out dependencies"; the PR was never updated further and was not merged. This is a single, non-exhaustive report (no gcompat usage confirmed explicitly), but it's concrete evidence that the naive "official tarball + Alpine" path fails in practice, consistent with gcompat's own documented limitations.
• Other headless-Blender Docker projects found in this search (BlenderKit/headless-blender-container, HaiyiMei/blender-docker-headless, LinuxServer.io's docker-blender) all use glibc-based bases (Ubuntu/Debian), not Alpine — i.e. nobody surveyed here ships a working Alpine+official-tarball image. This absence is itself weak corroborating evidence that the glibc-tarball-on-Alpine path isn't a well-trodden, working setup.

Implication for this repo

If Alpine is being considered as a smaller/leaner base for the CI image:

1. The current approach (download official glibc tarball from download.blender.org, per Dockerfile / scripts/resolve-blender-url.sh) cannot be ported to Alpine as-is — no glibc, and gcompat is not a credible fix for something as large/complex as Blender (per gcompat's own docs, and per the one real attempt found, which failed).
2. The only musl-native path found, Alpine's blender-headless package, exists only on edge — adopting Alpine would mean giving up the pinned/reproducible-version approach this repo currently uses for both Godot and Blender, in favor of tracking Alpine's rolling branch, or manually backporting/building the aport for a stable branch (extra maintenance burden not costed here).
3. No evidence was found either way (positive or negative) on whether the Alpine blender-headless package's Python/--background scripting behaves identically to the official build for .blend import — only that the package is described as built for that use case.

This is a real argument against Alpine for this image unless the team is willing to (a) pin to Alpine edge and accept its churn, or (b) take on maintaining a backport of the blender/blender-headless aport for a stable Alpine branch themselves.

Sources

• https://www.blender.org/download/requirements/
• https://www.blender.org/download/
• https://developer.blender.org/docs/handbook/building_blender/linux/ (403 on direct fetch; referenced via search summary)
• https://wiki.alpinelinux.org/wiki/Running_glibc_programs (403 on direct fetch; referenced via search summary)
• https://github.com/rs--/gcompat
• https://github.com/Stantheman/gcompat
• https://pkgs.alpinelinux.org/packages?name=gcompat
• https://pkgs.alpinelinux.org/package/edge/community/x86_64/blender
• https://pkgs.alpinelinux.org/package/edge/community/x86_64/blender-headless
• https://github.com/ikester/blender-docker/pull/1 (secondary/community)
• https://github.com/BlenderKit/headless-blender-container (secondary, uses Ubuntu — corroborates absence of a working Alpine setup)