# Does official Blender run under Alpine/musl?

Research for [wayfinder ticket #5](https://git.arthurerlich.de/haylan/godot-ci/issues/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)