Make optional RealESRGAN wheel prebuild opt-in

Dockerfile

@@ -1,14 +1,3 @@
-# ---- builder: patch + build wheels for Real-ESRGAN's broken-on-3.14 deps ----
-# basicsr/gfpgan/facexlib read their version via exec()+locals()['__version__'],
-# which raises KeyError on Python 3.13+ (PEP 667). Build patched wheels here so
-# the final image / Cookbook never has to compile the broken sdists. See
-# docker/build-realesrgan-wheels.sh for the full rationale.
-FROM python:3.14-slim AS realesrgan-wheels
-RUN apt-get update && apt-get install -y --no-install-recommends curl \
-    && rm -rf /var/lib/apt/lists/*
-COPY docker/build-realesrgan-wheels.sh /usr/local/bin/build-realesrgan-wheels.sh
-RUN bash /usr/local/bin/build-realesrgan-wheels.sh /wheels
-
 FROM python:3.14-slim
 
 # System deps. tmux is required by Cookbook for background downloads/serves.
@@ -81,14 +70,19 @@ RUN pip install --no-cache-dir -r requirements.txt \
 # lib installed above; see the apt note near the top of this stage.
 RUN pip install --no-cache-dir python-magic==0.4.27
 
-# Pre-install the patched basicsr/gfpgan/facexlib wheels built in the
+# Optional: pre-install patched basicsr/gfpgan/facexlib wheels for Real-ESRGAN.
-# realesrgan-wheels stage (--no-deps keeps the image lean — torch & friends are
+# These are only needed by the optional Gallery/Cookbook upscaling path. Keep
-# pulled only when realesrgan is actually installed). With these dists already
+# the default image build focused on core Odysseus so CI and Dockge updates do
-# satisfied, the Cookbook's plain `pip install realesrgan` resolves them from
+# not block on this expensive optional build step.
-# wheels instead of rebuilding the sdists that fail on Python 3.14.
+ARG PREBUILD_REALESRGAN_WHEELS=false
-COPY --from=realesrgan-wheels /wheels/ /tmp/odysseus-wheels/
+COPY docker/build-realesrgan-wheels.sh /usr/local/bin/build-realesrgan-wheels.sh
-RUN pip install --no-cache-dir --no-deps /tmp/odysseus-wheels/*.whl \
+RUN if [ "${PREBUILD_REALESRGAN_WHEELS}" = "true" ]; then \
-    && rm -rf /tmp/odysseus-wheels
+      bash /usr/local/bin/build-realesrgan-wheels.sh /tmp/odysseus-wheels \
+      && pip install --no-cache-dir --no-deps /tmp/odysseus-wheels/*.whl \
+      && rm -rf /tmp/odysseus-wheels; \
+    else \
+      echo "Skipping optional Real-ESRGAN wheel prebuild."; \
+    fi
 
 # Copy app code
 COPY . .

docs/wilkensxl-build.md

@@ -34,3 +34,15 @@ The loader does not remove all porting work, but it reduces it. Most local
 behavior should live behind addon manifests, so future upstream updates only
 need the loader compatibility checked plus any addons that touch changed
 internals.
+
+## Optional image extras
+
+The Docker image skips the optional Real-ESRGAN wheel prebuild by default. That
+keeps normal CI and Dockge updates from blocking on optional Gallery upscaling
+dependencies.
+
+To include the prebuilt Real-ESRGAN helper wheels in a custom image, build with:
+
+```text
+--build-arg PREBUILD_REALESRGAN_WHEELS=true
+```