PyMuPDF 1.26.7 - Building docker image with Python 3.14 and Alpine 3.23 is not working

[matpag]

Description of the bug

Hi guys,
I'm trying to build a Docker image of a Python project with PyMuPDF 1.26.7, Python 3.14 and using alpine 3.23 as base image but when I reach the pip install command I get this error:

I run the build docker command with --platform linux/amd64

# ....
#8 8.503 Collecting PyMuPDF==1.26.7 (from -r requirements.txt (line 13))
#8 8.558   Downloading pymupdf-1.26.7.tar.gz (84.3 MB)
#8 14.00      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 84.3/84.3 MB 15.6 MB/s  0:00:05
#8 14.77   Getting requirements to build wheel: started
#8 15.12   Getting requirements to build wheel: finished with status 'done'
#8 15.12   Installing backend dependencies: started
#8 18.76   Installing backend dependencies: finished with status 'done'
#8 18.76   Preparing metadata (pyproject.toml): started
#8 27.93   Preparing metadata (pyproject.toml): finished with status 'error'
#8 27.94   error: subprocess-exited-with-error
#8 27.94   
#8 27.94   × Preparing metadata (pyproject.toml) did not run successfully.
#8 27.94   │ exit code: 1
#8 27.94   ╰─> [86 lines of output]
#8 27.94       setup.py:221:<module>(): ### Starting.
#8 27.94       setup.py:222:<module>(): os.getcwd()='/tmp/pip-install-lh0m688o/pymupdf_14a96e11d7f34206847c2a243a1856bf'
#8 27.94       setup.py:222:<module>(): platform.machine()='x86_64'
#8 27.94       setup.py:222:<module>(): platform.platform()='Linux-6.12.54-linuxkit-x86_64-with-musl1'
#8 27.94       setup.py:222:<module>(): platform.python_implementation()='CPython'
#8 27.94       setup.py:222:<module>(): platform.python_version()='3.14.2'
#8 27.94       setup.py:222:<module>(): platform.system()='Linux'
#8 27.94       setup.py:222:<module>(): platform.uname()=uname_result(system='Linux', node='buildkitsandbox', release='6.12.54-linuxkit', version='#1 SMP Tue Nov  4 21:21:47 UTC 2025', machine='x86_64')
#8 27.94       setup.py:222:<module>(): sys.executable='/usr/local/bin/python3.14'
#8 27.94       setup.py:222:<module>(): sys.version='3.14.2 (main, Dec  8 2025, 20:32:04) [GCC 15.2.0]'
#8 27.94       setup.py:222:<module>(): sys.version_info=sys.version_info(major=3, minor=14, micro=2, releaselevel='final', serial=0)
#8 27.94       setup.py:222:<module>(): list(sys.version_info)=[3, 14, 2, 'final', 0]
#8 27.94       setup.py:222:<module>(): sysconfig.get_config_var("Py_GIL_DISABLED")=0
#8 27.94       setup.py:222:<module>(): sys._is_gil_enabled()=True
#8 27.94       setup.py:222:<module>(): CPU bits: 64
#8 27.94       setup.py:222:<module>(): sys.argv (3):
#8 27.94       setup.py:222:<module>():     0: '/usr/local/lib/python3.14/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py'
#8 27.94       setup.py:222:<module>():     1: 'prepare_metadata_for_build_wheel'
#8 27.94       setup.py:222:<module>():     2: '/tmp/tmpf5vz74h3'
#8 27.94       setup.py:222:<module>(): os.environ (14):
#8 27.94       setup.py:222:<module>():     HOME: '/root'
#8 27.94       setup.py:222:<module>():     LANG: 'C.UTF-8'
#8 27.94       setup.py:222:<module>():     LC_ALL: 'C.UTF-8'
#8 27.94       setup.py:222:<module>():     PATH: '/tmp/pip-build-env-pcmzi7mp/overlay/bin:/tmp/pip-build-env-pcmzi7mp/normal/bin:/usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin'
#8 27.94       setup.py:222:<module>():     PIP_BUILD_TRACKER: '/tmp/pip-build-tracker-g37k8clz'
#8 27.94       setup.py:222:<module>():     PWD: '/'
#8 27.94       setup.py:222:<module>():     PYTHONNOUSERSITE: '1'
#8 27.94       setup.py:222:<module>():     PYTHONPATH: '/tmp/pip-build-env-pcmzi7mp/site'
#8 27.94       setup.py:222:<module>():     PYTHON_SHA256: 'ce543ab854bc256b61b71e9b27f831ffd1bfd60a479d639f8be7f9757cf573e9'
#8 27.94       setup.py:222:<module>():     PYTHON_VERSION: '3.14.2'
#8 27.94       setup.py:222:<module>():     SHLVL: '1'
#8 27.94       setup.py:222:<module>():     TZ: 'UTC'
#8 27.94       setup.py:222:<module>():     _PYPROJECT_HOOKS_BACKEND_PATH: '/tmp/pip-install-lh0m688o/pymupdf_14a96e11d7f34206847c2a243a1856bf'
#8 27.94       setup.py:222:<module>():     _PYPROJECT_HOOKS_BUILD_BACKEND: 'setup'
#8 27.94       setup.py:240:<module>(): Not defaulting to Python limited api because platform.python_version_tuple()=('3', '14', '2').
#8 27.94       setup.py:246:<module>(): PYMUPDF_SETUP_URL_WHEEL=None
#8 27.94       setup.py:249:<module>(): PYMUPDF_SETUP_DUMMY=None
#8 27.94       pipcl.py:907:tag_platform(): From self.tag_platform_: ret=None.
#8 27.94       pipcl.py:915:tag_platform(): From AUDITWHEEL_PLAT: ret=None.
#8 27.94       pipcl.py:930:tag_platform(): From sysconfig.get_platform(): ret='linux_x86_64'.
#8 27.94       pipcl.py:934:tag_platform(): tag_platform(): returning ret='linux_x86_64'.
#8 27.94       setup.py:456:get_mupdf_internal(): get_mupdf_internal(): out='dir' location=None
#8 27.94       setup.py:485:get_mupdf_internal(): Download location='https://mupdf.com/downloads/archive/mupdf-1.26.12-source.tar.gz' local_tgz='mupdf-1.26.12-source.tar.gz' name='mupdf-1.26.12-source'
#8 27.94       setup.py:495:get_mupdf_internal(): Downloading from location='https://mupdf.com/downloads/archive/mupdf-1.26.12-source.tar.gz' to local_tgz='mupdf-1.26.12-source.tar.gz'.
#8 27.94       setup.py:362:tar_extract(): Extracting mupdf-1.26.12-source.tar.gz
#8 27.94       setup.py:922:build_mupdf_unix(): Setting XCFLAGS and XCXXFLAGS to predefine TOFU_CJK_EXT.
#8 27.94       setup.py:954:build_mupdf_unix(): Running: cc --version
#8 27.94       cc (Alpine 15.2.0) 15.2.0
#8 27.94       Copyright (C) 2025 Free Software Foundation, Inc.
#8 27.94       This is free software; see the source for copying conditions.  There is NO
#8 27.94       warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
#8 27.94       
#8 27.94       setup.py:955:build_mupdf_unix(): Running: c++ --version
#8 27.94       /bin/sh: c++: not found
#8 27.94       Traceback (most recent call last):
#8 27.94         File "/usr/local/lib/python3.14/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 389, in <module>
#8 27.94           main()
#8 27.94           ~~~~^^
#8 27.94         File "/usr/local/lib/python3.14/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 373, in main
#8 27.94           json_out["return_val"] = hook(**hook_input["kwargs"])
#8 27.94                                    ~~~~^^^^^^^^^^^^^^^^^^^^^^^^
#8 27.94         File "/usr/local/lib/python3.14/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 178, in prepare_metadata_for_build_wheel
#8 27.94           whl_basename = backend.build_wheel(metadata_directory, config_settings)
#8 27.94         File "/tmp/pip-install-lh0m688o/pymupdf_14a96e11d7f34206847c2a243a1856bf/pipcl.py", line 722, in build_wheel
#8 27.94           items = self._call_fn_build(config_settings)
#8 27.94         File "/tmp/pip-install-lh0m688o/pymupdf_14a96e11d7f34206847c2a243a1856bf/pipcl.py", line 1008, in _call_fn_build
#8 27.94           ret = self.fn_build()
#8 27.94         File "/tmp/pip-install-lh0m688o/pymupdf_14a96e11d7f34206847c2a243a1856bf/setup.py", line 623, in build
#8 27.94           mupdf_build_dir = build_mupdf_unix(
#8 27.94                   mupdf_local,
#8 27.94           ...<5 lines>...
#8 27.94                   PYMUPDF_SETUP_SWIG,
#8 27.94                   )
#8 27.94         File "/tmp/pip-install-lh0m688o/pymupdf_14a96e11d7f34206847c2a243a1856bf/setup.py", line 955, in build_mupdf_unix
#8 27.94           pipcl.run(f'{cxx} --version')
#8 27.94           ~~~~~~~~~^^^^^^^^^^^^^^^^^^^^
#8 27.94         File "/tmp/pip-install-lh0m688o/pymupdf_14a96e11d7f34206847c2a243a1856bf/pipcl.py", line 2380, in run
#8 27.94           cp = subprocess.run(
#8 27.94                   command2,
#8 27.94           ...<7 lines>...
#8 27.94                   timeout=timeout,
#8 27.94                   )
#8 27.94         File "/usr/local/lib/python3.14/subprocess.py", line 577, in run
#8 27.94           raise CalledProcessError(retcode, process.args,
#8 27.94                                    output=stdout, stderr=stderr)
#8 27.94       subprocess.CalledProcessError: Command 'c++ --version' returned non-zero exit status 127.
#8 27.94       [end of output]
#8 27.94   
#8 27.94   note: This error originates from a subprocess, and is likely not a problem with pip.
#8 27.94 error: metadata-generation-failed
#8 27.94 
#8 27.94 × Encountered error while generating package metadata.
#8 27.94 ╰─> PyMuPDF
#8 27.94 
#8 27.94 note: This is an issue with the package mentioned above, not pip.
#8 27.94 hint: See above for details.
#8 ERROR: process "/bin/sh -c pip3 install --upgrade pip &&     pip3 install -r requirements.txt" did not complete successfully: exit code: 1

I already tried manually installing libstdc++ thinking maybe of a missing dependency but does not work.

Are there some incompatibilities now? Because the previous setup we had:

python:3.12-alpine3.20
PyMuPDF==1.25.1

worked perfectly.

This combination is not working either:

python:3.12-alpine3.20
PyMuPDF==1.26.7

but this does:

python:3.14-alpine3.23
PyMuPDF==1.25.1

Do you have any advice? Thanks in advance.

How to reproduce the bug

Dockerfile:

FROM python:3.14-alpine3.23

ENV LANG=C.UTF-8
ENV LC_ALL=C.UTF-8
ENV TZ=UTC

RUN apk update && \
    apk add --no-cache --virtual .build-deps \
    ca-certificates gcc linux-headers musl-dev dos2unix \
    libffi-dev jpeg-dev zlib-dev freetype curl-dev openssl \
    libstdc++

COPY ./requirements.txt /

RUN pip3 install --upgrade pip && \
    pip3 install -r requirements.txt

RUN echo 'You wont reach here'

requirements.txt

PyMuPDF==1.26.7

Docker build command:
docker build --progress plain --platform linux/amd64 -t pymupdftest:1.0.0 .

PyMuPDF version

1.26.7

Operating system

MacOS

Python version

3.14

[julian-smith-artifex-com]

Thanks for the report.

1. The available wheels do not match your docker system, probably because the system is using musl libc instead of glibc.
2. So pip is attempting to build from source.
3. This fails because there is no C++ compiler on your docker system.

I think we might be missing wheels for linux-musl in recent releases. I'll look into this and hopefully upload a new wheel in the next few days.

In the meantime, if you install development tools such as C and C++ compilers, and make, the build should succeed.

[julian-smith-artifex-com]

I've just uploaded musl wheel pymupdf-1.26.7-cp310-abi3-musllinux_1_2_x86_64.whl to pypi.org.

Hopefully your build will now install this wheel directly instead of attempting to build from source.

Please let me know whether this works for you.

[matpag]

It works fine now, thank you for the fast response! :)