Document tradeoffs of Python distributions

[johnthagen]

As mentioned by @bwoodsend in

• Document python-build-standalone as glibc compatibility solution #9124 (comment)

The Pyinstaller docs could benefit from a section in the documentation discussing the tradeoffs between different Python distributions and their effect on portability/binary size/etc of Pyinstaller-produced binaries.

Some specific distributions that come to mind

• python-build-standalone (popularized by uv)
• deadsnakes PPA
• System Debian/Ubuntu/RHEL/Rocky Linux
• pyenv
• Homebrew
• Python.org installers
• Conda
• Official python container image: https://hub.docker.com/_/python

[polarathene]

Just some feedback and relevant snippets from the referenced closed/locked PR, should anyone work towards such docs hopefully this is helpful info :)

---

#9124 (comment)

Document that python-build-standalone is a possible solution to deal with Linux/GNU glibc compatibility issues.

This is something that I personally struggled with for a long time (keeping an up-to-date CPython available on old-enough Linux OS to build compatible PyInstaller binaries).

#9124 (comment)

The way you've written that change, it's implying that just using those Python environments is enough? That's not really the case.
You still need to build in an old container to control the glibc dependencies of any libraries you pull in.
The best that those builds can do is replace deadsnakes.

While these are valid concerns, if using Zig you can still use a modern build environment instead of relying on the friction of an outdated / EOL build environment that's commonly used to address glibc compatibility concerns.

Zig is capable of not only cross-compilation to different archs and platforms, but also at targeting lower glibc versions.

• I have encountered one issue with Zig thus far when building Python packages via sdists, some do link compiled object files with --exclude-libs=ALL (which is presently not supported by Zig). Not always a blocker as some packages are fine to continue using their bdist, there's unmaintained packages like pprintpp that won't build for Python 3.11 or newer for example that have no glibc concerns.
• Another issue with cross-compiling (not necessarily zig specific I think) I ran into was with the cryptography package that uses Rust maturin for it's sdist build. It would bring in Rust via rustup implicitly installing that and without looking further yet, appeared to be detecting the host platform to build without a way for me to override it. I had used maturin's ENV for PYO3 to point to the aarch64 copy of python-build-standalone to target, along with cargo's own CARGO_BUILD_TARGET set to the ARM64 target, but it still used AMD64/x86_64 arch as the target 🤷‍♂️

This was for another project but should be a helpful way to check from a dist dir of any libs you'd bundle (not usable with onefile which obscures the symbols within the executable):

# Find shared libraries from this location, then identify the minimal glibc version required at runtime:
# Using: https://github.com/sharkdp/fd
fd '\.so(\..+)?$' aarch64/dist/ --exec bash -c 'readelf -W --version-info --dyn-syms "{}" | grep "Name: GLIBC" | sed -re "s/.*GLIBC_(.+) Flags.*/\1/g" | sort -t . -k1,1n -k2,2n | tail -n 1 | echo "$(cat)- {}"' | sort -t . -k1,1n -k2,2n

2.17 - aarch64/dist/cryptography/hazmat/bindings/_rust.so
2.17 - aarch64/dist/google/_upb/_message.so

---

system libs portability/compatibility caveat (sdist/bdist?):

#9124 (comment)

The other issue is system libraries pulled in as dependencies of not fully self contained PyPI packages (mostly thinking Qt).

I would need more context regarding this concern.

• If this is about libs at build-time via the linker, it should only be linking to the DT_SONAME for dynamic links, which will be queried at runtime to load. If that's overly specific I'm not sure how that'd be improved on an older build system?
• If this is about system libs linking with symbols, similar to the PyPi packages bdists supplied libraries concern, you may need to bring in your own library copies and add them to a search path to be used instead (as is the usual workaround to avoid using system libs when that's an issue).

I've had links to system libraries like OpenSSL, which while built on a newer glibc did not bring in those symbols into the build since they're not relevant to linking to symbols of OpenSSL 😅 (major version differences between the OpenSSL 1.x and 3.x transition are valid though, but that's two separate builds regardless, unless you bundle those libraries to load via leveraging patchelf --set-rpath '$ORIGIN').

I imagine if the build environment is old enough, and you needed to link to modern OpenSSL 3.x, you may lack that on the old build environment without supplying it yourself. So anything like that kinda works both ways 🤷‍♂️

---

Outdated python-build-standalone caveat:

#9124 (comment)

it should also mention the PyInstaller-specific caveats (like the lack of compatibility with splash screen due to statically linked Tcl/Tk - see #9012 and https://github.com/orgs/pyinstaller/discussions/9079).

This is probably outdated information now, since Aug 2025:

• Related PR: Build libtcl, libtk, and _tkinter as shared objects, and remove Tix astral-sh/python-build-standalone#676
• GH Release tag 20250808

---

Installing package bdists by platform flag:

#9124 (comment)

pip's --platform flag doesn't really handle manylinux tags properly
I'd expect to be able to use --platform=manylinux_2_17_x86_64 and it would collect wheels with glibc targets 2.17 or lower but instead it'll only accept exactly 2.17.

I've not looked into this personally, or compared it to the equivalent support with UV.

Information on that comment was lacking a bit. As the platform is focused on glibc 2.17, presumably there is something more specific about that, but linking to symbols below 2.17 should be fine, even the latest glibc in builds will include versioned symbols from early versions of glibc.

EDIT: Actually I think I understand now, this was about how the packages only install for that specific platform value, thus a package must publish for that platform like it would any other platform like x86_64-unknown-linux-gnu / aarch64-unknown-linux-gnu.

---

deadsnakes PPA caveats:

#9124 (comment)

Overall deadsnakes, while a decent option, still provided problems for reliable "latest CPython with a GLIBC that is always low enough for all Linux versions, including long-lived RHEL's".

[johnthagen]

This is probably outdated information now, since Aug 2025:

Note that python-build-standalone does still have Tk-related issues with PyInstaller

• Fails to open libtk8.6.so on Ubuntu 22.04 when bundled with PyInstaller astral-sh/python-build-standalone#746

[polarathene]

EDIT: Oh it seems that's already what python-build-standalone plans to do here: astral-sh/python-build-standalone#745

---

Note that python-build-standalone does still have Tk-related issues with PyInstaller

I am not that experienced with Python or familiar with Tk, but assuming this is sufficient of a reproduction it was quite easy to resolve:

main.py: (basic hello world example)

import tkinter as tk

root = tk.Tk()
a = tk.Label(root, text ="Hello World")
a.pack()

root.mainloop()

Reproduction environment:

# Docker reproduction environment
# - Install `uv` to install Python via python-build-standalone
# - Install `binutils` for PyInstaller
$ docker run --rm -it --volume ./main.py:/example/main.py --workdir /example --name reproduction fedora:42
$ dnf install -yq uv binutils

# UV from `0.8.7` provides python-build-standalone `20250808` (both Aug 2025)
# https://github.com/astral-sh/uv/releases/tag/0.8.7
# https://github.com/astral-sh/python-build-standalone/releases/tag/20250808
# These provide the Tk shared libs change for Mac/Linux builds:
# https://github.com/astral-sh/python-build-standalone/pull/676
$ uv --version
uv 0.8.11

# Add Python and init project with PyInstaller 6.16+ (`main.py` already provisioned via bind mount volume):
$ uv python install 3.13
$ uv init /example
$ uv add --dev pyinstaller>=6.16

# Try build project but fails because library could not be found:
$ uv run pyinstaller --onefile main.py
# ...
5187 INFO: Looking for dynamic libraries
5208 WARNING: Library not found: could not resolve 'libtk8.6.so', dependency of '/root/.local/share/uv/python/cpython-3.13.6-linux-x86_64-gnu/lib/python3.13/lib-dynload/_tkinter.cpython-313-x86_64-linux-gnu.so'.
5208 WARNING: Library not found: could not resolve 'libtcl8.6.so', dependency of '/root/.local/share/uv/python/cpython-3.13.6-linux-x86_64-gnu/lib/python3.13/lib-dynload/_tkinter.cpython-313-x86_64-linux-gnu.so'.
5214 INFO: Warnings written to /example/build/main/warn-main.txt

Inspect the failed dependency:

$ ldd /root/.local/share/uv/python/cpython-3.13.6-linux-x86_64-gnu/lib/python3.13/lib-dynload/_tkinter.cpython-313-x86_64-linux-gnu.so
        linux-vdso.so.1 (0x00007ffed2f60000)
        libtcl8.6.so => not found
        libtk8.6.so => not found
        libpthread.so.0 => /lib64/libpthread.so.0 (0x00007bd84c898000)
        libc.so.6 => /lib64/libc.so.6 (0x00007bd84c6a6000)
        /lib64/ld-linux-x86-64.so.2 (0x00007bd84c8b1000)

$ dnf install -yq fd-find patchelf

# Locate copies of the libs on the system:
$ fd --hidden 'libtcl|libtk' /
/root/.local/share/uv/python/cpython-3.13.6-linux-x86_64-gnu/lib/libtcl8.6.so
/root/.local/share/uv/python/cpython-3.13.6-linux-x86_64-gnu/lib/libtk8.6.so

# Confirm these are direct deps from the failed library (not via transitive deps):
$ patchelf --print-needed /root/.local/share/uv/python/cpython-3.13.6-linux-x86_64-gnu/lib/python3.13/lib-dynload/_tkinter.cpython-313-x86_64-linux-gnu.so
libtcl8.6.so
libtk8.6.so
libpthread.so.0
libc.so.6

# Check rpath (it's blank so none is set):
$ patchelf --print-rpath /root/.local/share/uv/python/cpython-3.13.6-linux-x86_64-gnu/lib/python3.13/lib-dynload/_tkinter.cpython-313-x86_64-linux-gnu.so

An easy fix that python-build-standalone could apply - Set a relative RPath from the library to two parent directories back, so that the libs can be found by the ld.so resolver (NOTE: You can also provide an absolute path via LD_LIBRARY_PATH ENV or add it to your build systems /etc/ld.so.conf.d/some-name.conf file, then run ldconfig and you'll find ldconfig -p outputs an entry).

$ patchelf --set-rpath '$ORIGIN/../..' /root/.local/share/uv/python/cpython-3.13.6-linux-x86_64-gnu/lib/python3.13/lib-dynload/_tkinter.cpython-313-x86_64-linux-gnu.so

# Or alternative as per note (NOTE: Unlike Nuitka, PyInstaller does not adjust the RPath):
#echo '/root/.local/share/uv/python/cpython-3.13.6-linux-x86_64-gnu/lib' > /etc/ld.so.conf.d/python-build-standalone.conf
#ldconfig
#ldconfig -p | grep libtk

After you've made it so the libraries can be discovered, the build is successful:

# Using `--onedir` instead so that you can inspect the needed libraries were copied over:
$ uv run pyinstaller --onedir main.py
$ ls dist/main/_internal
_tcl_data  _tk_data  base_library.zip  libpython3.13.so.1.0  libtcl8.6.so  libtk8.6.so  python3.13  tcl8

If you didn't set the RPath, library search dirs will be checked as usual for resolving, so any system provided libs would be used (despite the local copies made by PyInstaller), as such if you did the ldconfig / LD_LIBRARY_PATH approach you get the following:

$ ldd dist/main/_internal/python3.13/lib-dynload/_tkinter.cpython-313-x86_64-linux-gnu.so
        linux-vdso.so.1 (0x00007ffe632fa000)
        libtcl8.6.so => /root/.local/share/uv/python/cpython-3.13.6-linux-x86_64-gnu/lib/libtcl8.6.so (0x000072a774ab0000)
        libtk8.6.so => /root/.local/share/uv/python/cpython-3.13.6-linux-x86_64-gnu/lib/libtk8.6.so (0x000072a7747fa000)
        libpthread.so.0 => /lib64/libpthread.so.0 (0x000072a7747f6000)
        libc.so.6 => /lib64/libc.so.6 (0x000072a774604000)
        libdl.so.2 => /lib64/libdl.so.2 (0x000072a7745fe000)
        libm.so.6 => /lib64/libm.so.6 (0x000072a774510000)
        /lib64/ld-linux-x86-64.so.2 (0x000072a774c7f000)

Shouldn't be a concern however as PyInstaller's executable will set LD_LIBRARY_PATH to it's _internal/ location, which would give priority to loading your bundled libs at runtime. If they weren't bundled however, then it'd be up to the system to provide them.

I'm running this from WSL in a container on Windows, so a UI lib isn't going to work out there, but regardless of how you helped PyInstaller resolve the libraries, this is the runtime output in my case (which is technically successful):

$ dist/main/main

Traceback (most recent call last):
  File "main.py", line 3, in <module>
    root = tk.Tk()
  File "tkinter/__init__.py", line 2459, in __init__
_tkinter.TclError: no display name and no $DISPLAY environment variable
[PYI-504:ERROR] Failed to execute script 'main' due to unhandled exception!

From a separate console, I can copy out a binary from a --onefile build and get the same success on Ubuntu 22.04 / 24.04 which you raised as a difference for you (which I'm unable to reproduce and is likely due to difference of what your two Ubuntu environments had available to satisfy the dep from system paths):

# Copy `main` binary from the `reproduction` container to the local filesystem:
$ docker cp reproduction:/example/dist/main main

# Run Ubuntu 22.04 with the `main` binary as a command found via the `PATH` ENV (includes `/usr/local/bin`):
$ docker run --rm -it --volume ./main:/usr/local/bin/main ubuntu:22.04 main
Traceback (most recent call last):
  File "main.py", line 3, in <module>
  File "tkinter/__init__.py", line 2459, in __init__
_tkinter.TclError: no display name and no $DISPLAY environment variable
[PYI-7:ERROR] Failed to execute script 'main' due to unhandled exception!