1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239.. _quirks:
===============
Behavior Quirks
===============
While these Python distributions are intended to be broadly compatible
with the Python ecosystem, there are a few known behavior quirks that
affect specific environments, packages, or use cases.
.. _quirk_backspace_key:
If special keys do not work in the Python REPL
==============================================
If you attempt to run ``python`` and the backspace key doesn't
erase characters or the arrow keys don't work as expected, this
is because the executable can't find the *terminfo database*.
If this happens, the Python REPL will print the following warning
message on startup::
Cannot read termcap database;
using dumb terminal settings.
When you type a special key like the backspace key, this is
registered as a key press. There is special software (typically
``readline`` or ``libedit``) that most interactive programs use
that intercepts these special key presses and converts them into
special behavior, such as moving the cursor back instead of
forward. But because computer environments are different,
there needs to be some definition of how these special
behaviors are performed. This is the *terminfo database*.
When ``readline`` and ``libedit`` are compiled, there is
typically a hard-coded set of search locations for the
*terminfo database* baked into the built library. And when
you build a program (like Python) locally, you link against
``readline`` or ``libedit`` and get these default locations
*for free*.
These Python distributions compile and use their own version of
``libedit`` to avoid a dependency on what is (or isn't) installed on
your system. This means that they do not use your system-provided
libraries for reading the *terminfo database*. This version of
``libedit`` is configured to look for in locations that should work for
most OSes (specifically, ``/usr/share/terminfo`` on macOS, and
``/etc/terminfo``, ``/lib/terminfo``, and ``/usr/share/terminfo`` on
Linux, which should cover all major Linux distributions), but it is
possible that your environment has it somewhere else. If your OS stores
the *terminfo database* in an uncommon location, you can set the
``TERMINFO_DIRS`` environment variable so that ``libedit`` can find it.
For instance, you may need to do something like:
$ TERMINFO_DIRS=/uncommon/place/terminfo install/bin/python3.10
If you are running on a relatively standard OS and this does not work
out of the box, please file a bug report so we can add the location of
the *terminfo database* to the build.
For convenience, a relatively recent copy of the terminfo database
is distributed in the ``share/terminfo`` directory (``../../share/terminfo``
relative to the ``bin/python3`` executable) in Linux distributions. Note
that ncurses and derived libraries don't know how to find this directory
since they are configured to use absolute paths to the terminfo database
and the absolute path of the Python distribution is obviously not known
at build time! So actually using this bundled terminfo database will
require custom code setting ``TERMINFO_DIRS`` before
ncurses/libedit/readline are loaded.
.. _quirk_macos_no_tix:
No tix on UNIX
==============
Tix is an old widget library for Tcl/Tk. Python previously had a wrapper
for it in ``tkinter.tix``, but it was deprecated in Python 3.6 (the
recommendation is to use ``tkinter.ttk``) and removed in Python 3.13.
The macOS and Linux distributions from this project do not build and
ship Tix, even for Python versions 3.12 and below.
We had previously attempted to ship Tix support on Linux, but it was
broken and nobody reported an issue about it. The macOS distributions
from this project never shipped support for Tix. The official Python.org
macOS installers and Apple's build of Python do not ship support for
Tix, either, so this project behaves similarly to those distributions.
.. _quirk_windows_no_pip:
No ``pip.exe`` on Windows
=========================
The Windows distributions have ``pip`` installed however no ``Scripts/pip.exe``,
``Scripts/pip3.exe``, and ``Scripts/pipX.Y.exe`` files are provided because
the way these executables are built isn't portable. (It might be possible to
change how these are built to make them portable.)
To use pip, run ``python.exe -m pip``. (It is generally a best practice to
invoke pip via ``python -m pip`` on all platforms so you can be explicit
about the ``python`` executable that pip uses.)
.. _quirk_macos_linking:
Linking Static Library on macOS
===============================
Python 3.10+ makes use of the ``__builtin_available()`` compiler feature.
This functionality requires a symbol from ``libclang_rt``, which may not
be linked by default. Failure to link against ``libclang_rt`` could result
in a linker error due to an undefined symbol ``___isOSVersionAtLeast``.
To work around this linker failure, link against the static library
``libclang_rt.<platform>.a`` present in the Clang installation. e.g.
``libclang_rt.osx.a``. You can find this library by invoking
``clang --print-search-dirs`` and looking in the ``lib/darwin`` directory
under the printed ``libraries`` directory. An example path is
``/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/clang/12.0.0/lib/darwin/libclang_rt.osx.a``.
A copy of the ``libclang_rt.<platform>.a`` from the Clang used to build
the distribution is included in the archive. However, it isn't annotated
in ``PYTHON.json`` because we're unsure if using the file with another
build/version of Clang is supported. Use at your own risk.
See https://jonnyzzz.com/blog/2018/06/05/link-error-2/ and
https://jonnyzzz.com/blog/2018/06/13/link-error-3/ for more on this topic.
.. _quirk_linux_libedit:
Use of ``libedit`` on Linux
===========================
Python 3.10+ Linux distributions link against ``libedit`` (as opposed to
``readline``) by default, as ``libedit`` is supported on 3.10+ outside of
macOS.
Most Python builds on Linux will link against ``readline`` because ``readline``
is the dominant library on Linux.
Some functionality may behave subtly differently as a result of our choice
to link ``libedit`` by default. (We choose ``libedit`` by default to
avoid GPL licensing requirements of ``readline``.)
.. _quirk_references_to_build_paths:
References to Build-Time Paths
==============================
The built Python distribution captures some absolute paths and other
build-time configuration in a handful of files:
* In a ``_sysconfigdata_*.py`` file in the standard library. e.g.
``lib/python3.10/_sysconfigdata__linux_x86_64-linux-gnu.py``.
* In a ``Makefile`` under a ``config-*`` directory in the standard library.
e.g. ``lib/python3.10/config-3.10-x86_64-linux-gnu/Makefile``.
* In python-build-standalone's metadata file ``PYTHON.json`` (mostly
reflected values from ``_sysconfigdata_*.py``).
Each of these serves a different use case. But the general theme is various
aspects of the Python distribution attempt to capture how Python was built.
The most common use of these values is to facilitate compiling or linking
other software against this Python build. For example, the ``_sysconfigdata*``
module is loaded by the `sysconfig <https://docs.python.org/3/library/sysconfig.html>`_
module. ``sysconfig`` in turn is used by packaging tools like ``setuptools``
and ``pip`` to figure out how to invoke a compiler for e.g. compiling C
extensions from source.
When installed by `uv <https://docs.astral.sh/uv/>`_, these absolute
paths are fixed up to point to the actual location on your system where
the distribution was installed, so **this quirk generally does not
affect uv users**. The third-party tool `sysconfigpatcher
<https://github.com/bluss/sysconfigpatcher>`_ also does this and might
be helpful to use or reference if you are installing these distributions
on your own.
In particular, you may see references to our install-time paths on the
build infrastructure, e.g., ``/build`` and ``/install`` on Linux, a
particular SDK in ``/Applications/Xcode.app`` on macOS, and temporary
directories on Windows.
Also, Python reports the compiler and flags in use, just in case it is
needed to make binary-compatible extensions. On Linux, for instance, we
use our own builds of Clang and potentially some flags (warnings,
optimizations, locations of the build environment) that do not work or
apply in other environments. We try to configure Python to remove
unneeded flags and absolute paths to files in the build environment.
references to build-time paths. Python's ``sysconfig`` system requires
listing a compiler, so we leave it set to ``clang`` without the absolute
path, but you should be able to use another compiler like ``gcc`` to
compile extensions, too.
If there is a build time normalization that you think should be performed to
make distributions more portable, please file a GitHub issue.
.. _quirk_former:
.. _quirk_missing_libcrypt:
.. _quirk_linux_libx11:
Former quirks
=============
The following quirks were previously listed on this page but have since
been resolved.
* "Static Linking of musl libc Prevents Extension Module Library
Loading": Starting with the 20250311 release, the default musl
distributions are dynamically linked by default, so extension modules
should work properly. Note that these now require a system-wide
installation of the musl C library. (This is present by default on
musl-based OSes like Alpine, and many glibc-based distros have a
``musl`` package you can safely co-install with glibc, too.) If you
specifically need a statically-linked binary, variants with the
``+static`` build option are available, but these retain the quirk
that compiled extension modules (e.g., ``musllinux`` wheels) cannot be
loaded.
* "Missing ``libcrypt.so.1``": The 20230507 release and earlier required
the system library ``libcrypt.so.1``, which stopped being shipped by
default in several Linux distributions around 2022. Starting with the
20230726 release, this dependency is now only needed by the deprecated
``crypt`` module, which only exists on Python 3.12 and lower. If you
still need this module, your OS may offer a ``libxcrypt`` package to
provide this library. Alternatively, there are suggestions in `What's
New in Python 3.13`_ about third-party replacements for the ``crypt``
module.
* "Static Linking of ``libX11`` / Incompatibility with PyQt on Linux":
The 20220318 release and earlier exported dynamic symbols for the
internal, statically-linked build of ``libX11`` and other libraries.
These would cause conflicts and potential crashes when using
third-party extension modules such as PyQt that load an actual shared
``libX11`` library (usually provided by your OS). Starting with the
20220502 release, symbols from internal dependencies are no longer
exported.
.. _What's New in Python 3.13: https://docs.python.org/3/whatsnew/3.13.html#whatsnew313-pep594