3. Configure Python — Python documentation
3. Configure Python
3.1. Configure Options
List all ./configure
script options using:
./configure --help
See also the Misc/SpecialBuilds.txt
in the Python source distribution.
3.1.1. General Options
- --enable-loadable-sqlite-extensions
Support loadable extensions in the
_sqlite
extension module (default is no).See the sqlite3.Connection.enable_load_extension() method of the sqlite3 module.
New in version 3.6.
- --disable-ipv6
- Disable IPv6 support (enabled by default if supported), see the socket module.
- --enable-big-digits=[15|30]
Define the size in bits of Python int digits: 15 or 30 bits.
By default, the number of bits is selected depending on
sizeof(void*)
: 30 bits ifvoid*
size is 64-bit or larger, 15 bits otherwise.Define the
PYLONG_BITS_IN_DIGIT
to15
or30
.
- --with-cxx-main
- --with-cxx-main=COMPILER
- Compile the Python
main()
function and link Python executable with C++ compiler:$CXX
, or COMPILER if specified.
- --with-suffix=SUFFIX
Set the Python executable suffix to SUFFIX.
The default suffix is
.exe
on Windows and macOS (python.exe
executable), and an empty string on other platforms (python
executable).
- --with-tzpath=<list of absolute paths separated by pathsep>
Select the default time zone search path for zoneinfo.TZPATH. See the Compile-time configuration of the zoneinfo module.
Default:
/usr/share/zoneinfo:/usr/lib/zoneinfo:/usr/share/lib/zoneinfo:/etc/zoneinfo
.See os.pathsep path separator.
New in version 3.9.
- --without-decimal-contextvar
Build the
_decimal
extension module using a thread-local context rather than a coroutine-local context (default), see the decimal module.See decimal.HAVE_CONTEXTVAR and the contextvars module.
New in version 3.9.
- --with-dbmliborder=db1:db2:...
Override order to check db backends for the dbm module
A valid value is a colon (
:
) separated string with the backend names:ndbm
;gdbm
;bdb
.
- --without-c-locale-coercion
Disable C locale coercion to a UTF-8 based locale (enabled by default).
Don’t define the
PY_COERCE_C_LOCALE
macro.See PYTHONCOERCECLOCALE and the PEP 538.
- --with-platlibdir=DIRNAME
Python library directory name (default is
lib
).Fedora and SuSE use
lib64
on 64-bit platforms.See sys.platlibdir.
New in version 3.9.
- --with-wheel-pkg-dir=PATH
Directory of wheel packages used by the ensurepip module (none by default).
Some Linux distribution packaging policies recommend against bundling dependencies. For example, Fedora installs wheel packages in the
/usr/share/python-wheels/
directory and don’t install theensurepip._bundled
package.New in version 3.10.
3.1.2. Install Options
- --disable-test-modules
Don’t build nor install test modules, like the test package or the
_testcapi
extension module (built and installed by default).New in version 3.10.
- --with-ensurepip=[upgrade|install|no]
Select the ensurepip command run on Python installation:
upgrade
(default): runpython -m ensurepip --altinstall --upgrade
command.install
: runpython -m ensurepip --altinstall
command;no
: don’t run ensurepip;
New in version 3.6.
3.1.3. Performance options
Configuring Python using --enable-optimizations --with-lto
(PGO + LTO) is recommended for best performance.
- --enable-optimizations
Enable Profile Guided Optimization (PGO) using PROFILE_TASK (disabled by default).
The C compiler Clang requires
llvm-profdata
program for PGO. On macOS, GCC also requires it: GCC is just an alias to Clang on macOS.Disable also semantic interposition in libpython if
--enable-shared
and GCC is used: add-fno-semantic-interposition
to the compiler and linker flags.New in version 3.6.
Changed in version 3.10: Use
-fno-semantic-interposition
on GCC.
- PROFILE_TASK
Environment variable used in the Makefile: Python command line arguments for the PGO generation task.
Default:
-m test --pgo --timeout=$(TESTTIMEOUT)
.New in version 3.8.
- --with-lto
Enable Link Time Optimization (LTO) in any build (disabled by default).
The C compiler Clang requires
llvm-ar
for LTO (ar
on macOS), as well as an LTO-aware linker (ld.gold
orlld
).New in version 3.6.
- --with-computed-gotos
- Enable computed gotos in evaluation loop (enabled by default on supported compilers).
- --without-pymalloc
Disable the specialized Python memory allocator pymalloc (enabled by default).
See also PYTHONMALLOC environment variable.
- --without-doc-strings
Disable static documentation strings to reduce the memory footprint (enabled by default). Documentation strings defined in Python are not affected.
Don’t define the
WITH_DOC_STRINGS
macro.See the
PyDoc_STRVAR()
macro.
- --enable-profiling
- Enable C-level code profiling with
gprof
(disabled by default).
3.1.4. Python Debug Build
A debug build is Python built with the --with-pydebug configure option.
Effects of a debug build:
- Display all warnings by default: the list of default warning filters is empty in the warnings module.
- Add
d
to sys.abiflags. - Add
sys.gettotalrefcount()
function. - Add -X showrefcount command line option.
- Add PYTHONTHREADDEBUG environment variable.
- Add support for the
__ltrace__
variable: enable low-level tracing in the bytecode evaluation loop if the variable is defined. - Install debug hooks on memory allocators to detect buffer overflow and other memory errors.
- Define
Py_DEBUG
andPy_REF_DEBUG
macros. - Add runtime checks: code surroundeded by
#ifdef Py_DEBUG
and#endif
. Enableassert(...)
and_PyObject_ASSERT(...)
assertions: don’t set theNDEBUG
macro (see also the --with-assertions configure option). Main runtime checks:- Add sanity checks on the function arguments.
- Unicode and int objects are created with their memory filled with a pattern to detect usage of uninitialized objects.
- Ensure that functions which can clear or replace the current exception are not called with an exception raised.
- The garbage collector (gc.collect() function) runs some basic checks on objects consistency.
- The
Py_SAFE_DOWNCAST()
macro checks for integer underflow and overflow when downcasting from wide types to narrow types.
See also the Python Development Mode and the --with-trace-refs configure option.
Changed in version 3.8: Release builds and debug builds are now ABI compatible: defining the Py_DEBUG
macro no longer implies the Py_TRACE_REFS
macro (see the --with-trace-refs option), which introduces the only ABI incompatibility.
3.1.5. Debug options
- --with-pydebug
- Build Python in debug mode: define the
Py_DEBUG
macro (disabled by default).
- --with-trace-refs
Enable tracing references for debugging purpose (disabled by default).
Effects:
Define the
Py_TRACE_REFS
macro.Add
sys.getobjects()
function.Add PYTHONDUMPREFS environment variable.
This build is not ABI compatible with release build (default build) or debug build (
Py_DEBUG
andPy_REF_DEBUG
macros).New in version 3.8.
- --with-assertions
Build with C assertions enabled (default is no):
assert(...);
and_PyObject_ASSERT(...);
.If set, the
NDEBUG
macro is not defined in the OPT compiler variable.See also the --with-pydebug option (debug build) which also enables assertions.
New in version 3.6.
- --with-valgrind
- Enable Valgrind support (default is no).
- --with-dtrace
Enable DTrace support (default is no).
See Instrumenting CPython with DTrace and SystemTap.
New in version 3.6.
- --with-address-sanitizer
Enable AddressSanitizer memory error detector,
asan
(default is no).New in version 3.6.
- --with-memory-sanitizer
Enable MemorySanitizer allocation error detector,
msan
(default is no).New in version 3.6.
- --with-undefined-behavior-sanitizer
Enable UndefinedBehaviorSanitizer undefined behaviour detector,
ubsan
(default is no).New in version 3.6.
3.1.6. Linker options
- --enable-shared
- Enable building a shared Python library:
libpython
(default is no).
- --without-static-libpython
Do not build
libpythonMAJOR.MINOR.a
and do not installpython.o
(built and enabled by default).New in version 3.10.
3.1.7. Libraries options
- --with-libs='lib1 ...'
- Link against additional libraries (default is no).
- --with-system-expat
- Build the
pyexpat
module using an installedexpat
library (default is no).
- --with-system-ffi
- Build the
_ctypes
extension module using an installedffi
library, see the ctypes module (default is system-dependent).
- --with-system-libmpdec
Build the
_decimal
extension module using an installedmpdec
library, see the decimal module (default is no).New in version 3.3.
- --with-readline=editline
Use
editline
library for backend of the readline module.Define the
WITH_EDITLINE
macro.New in version 3.10.
- --without-readline
Don’t build the readline module (built by default).
Don’t define the
HAVE_LIBREADLINE
macro.New in version 3.10.
- --with-tcltk-includes='-I...'
- Override search for Tcl and Tk include files.
- --with-tcltk-libs='-L...'
- Override search for Tcl and Tk libraries.
- --with-libm=STRING
- Override
libm
math library to STRING (default is system-dependent).
- --with-libc=STRING
- Override
libc
C library to STRING (default is system-dependent).
- --with-openssl=DIR
Root of the OpenSSL directory.
New in version 3.7.
- --with-openssl-rpath=[no|auto|DIR]
Set runtime library directory (rpath) for OpenSSL libraries:
no
(default): don’t set rpath;auto
: auto-detect rpath from --with-openssl andpkg-config
;DIR: set an explicit rpath.
New in version 3.10.
3.1.8. Security Options
- --with-hash-algorithm=[fnv|siphash24]
Select hash algorithm for use in
Python/pyhash.c
:siphash24
(default).fnv
;
New in version 3.4.
- --with-builtin-hashlib-hashes=md5,sha1,sha256,sha512,sha3,blake2
Built-in hash modules:
md5
;sha1
;sha256
;sha512
;sha3
(with shake);blake2
.
New in version 3.9.
- --with-ssl-default-suites=[python|openssl|STRING]
Override the OpenSSL default cipher suites string:
python
(default): use Python’s preferred selection;openssl
: leave OpenSSL’s defaults untouched;STRING: use a custom string
See the ssl module.
New in version 3.7.
Changed in version 3.10: The settings
python
and STRING also set TLS 1.2 as minimum protocol version.
3.1.9. macOS Options
See Mac/README.rst
.
- --enable-universalsdk
- --enable-universalsdk=SDKDIR
- Create a universal binary build. SDKDIR specifies which macOS SDK should be used to perform the build (default is no).
- --enable-framework
- --enable-framework=INSTALLDIR
- Create a Python.framework rather than a traditional Unix install. Optional INSTALLDIR specifies the installation path (default is no).
- --with-universal-archs=ARCH
Specify the kind of universal binary that should be created. This option is only valid when --enable-universalsdk is set.
Options:
universal2
;32-bit
;64-bit
;3-way
;intel
;intel-32
;intel-64
;all
.
- --with-framework-name=FRAMEWORK
- Specify the name for the python framework on macOS only valid when --enable-framework is set (default:
Python
).
3.2. Python Build System
3.2.1. Main files of the build system
configure.ac
=>configure
;Makefile.pre.in
=>Makefile
(created byconfigure
);pyconfig.h
(created byconfigure
);Modules/Setup
: C extensions built by the Makefile usingModule/makesetup
shell script;setup.py
: C extensions built using the distutils module.
3.2.2. Main build steps
- C files (
.c
) are built as object files (.o
). - A static
libpython
library (.a
) is created from objects files. python.o
and the staticlibpython
library are linked into the finalpython
program.- C extensions are built by the Makefile (see
Modules/Setup
) andpython setup.py build
.
3.2.3. Main Makefile targets
make
: Build Python with the standard library.make platform:
: build thepython
program, but don’t build the standard library extension modules.make profile-opt
: build Python using Profile Guided Optimization (PGO). You can use the configure --enable-optimizations option to make this the default target of themake
command (make all
or justmake
).make buildbottest
: Build Python and run the Python test suite, the same way than buildbots test Python. SetTESTTIMEOUT
variable (in seconds) to change the test timeout (1200 by default: 20 minutes).make install
: Build and install Python.make regen-all
: Regenerate (almost) all generated files;make regen-stdlib-module-names
andautoconf
must be run separately for the remaining generated files.make clean
: Remove built files.make distclean
: Same thanmake clean
, but remove also files created by the configure script.
3.2.4. C extensions
Some C extensions are built as built-in modules, like the sys
module. They are built with the Py_BUILD_CORE_BUILTIN
macro defined. Built-in modules have no __file__
attribute:
>>> import sys
>>> sys
<module 'sys' (built-in)>
>>> sys.__file__
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
AttributeError: module 'sys' has no attribute '__file__'
Other C extensins are built as dynamic libraries, like the _asyncio
module. They are built with the Py_BUILD_CORE_MODULE
macro defined. Example on Linux x86-64:
>>> import _asyncio
>>> _asyncio
<module '_asyncio' from '/usr/lib64/python3.9/lib-dynload/_asyncio.cpython-39-x86_64-linux-gnu.so'>
>>> _asyncio.__file__
'/usr/lib64/python3.9/lib-dynload/_asyncio.cpython-39-x86_64-linux-gnu.so'
Modules/Setup
is used to generate Makefile targets to build C extensions. At the beginning of the files, C extensions are built as built-in modules. Extensions defined after the *shared*
marker are built as dynamic libraries.
The setup.py
script only builds C extensions as shared libraries using the distutils module.
The PyAPI_FUNC()
, PyAPI_API()
and PyMODINIT_FUNC()
macros of Include/pyport.h
are defined differently depending if the Py_BUILD_CORE_MODULE
macro is defined:
- Use
Py_EXPORTED_SYMBOL
if thePy_BUILD_CORE_MODULE
is defined - Use
Py_IMPORTED_SYMBOL
otherwise.
If the Py_BUILD_CORE_BUILTIN
macro is used by mistake on a C extension built as a shared library, its PyInit_xxx()
function is not exported, causing an ImportError on import.
3.3. Compiler and linker flags
Options set by the ./configure
script and environment variables and used by Makefile
.
3.3.1. Preprocessor flags
- CONFIGURE_CPPFLAGS
Value of CPPFLAGS variable passed to the
./configure
script.New in version 3.6.
- CPPFLAGS
(Objective) C/C++ preprocessor flags, e.g.
-I<include dir>
if you have headers in a nonstandard directory<include dir>
.Both CPPFLAGS and LDFLAGS need to contain the shell’s value for setup.py to be able to build extension modules using the directories specified in the environment variables.
- BASECPPFLAGS
New in version 3.4.
- PY_CPPFLAGS
Extra preprocessor flags added for building the interpreter object files.
Default:
$(BASECPPFLAGS) -I. -I$(srcdir)/Include $(CONFIGURE_CPPFLAGS) $(CPPFLAGS)
.New in version 3.2.
3.3.2. Compiler flags
- CC
C compiler command.
Example:
gcc -pthread
.
- MAINCC
C compiler command used to build the
main()
function of programs likepython
.Variable set by the --with-cxx-main option of the configure script.
Default:
$(CC)
.
- CXX
C++ compiler command.
Used if the --with-cxx-main option is used.
Example:
g++ -pthread
.
- CFLAGS
- C compiler flags.
- CFLAGS_NODIST
CFLAGS_NODIST is used for building the interpreter and stdlib C extensions. Use it when a compiler flag should not be part of the distutils CFLAGS once Python is installed (:issue:`21121`).
New in version 3.5.
- EXTRA_CFLAGS
- Extra C compiler flags.
- CONFIGURE_CFLAGS
Value of CFLAGS variable passed to the
./configure
script.New in version 3.2.
- CONFIGURE_CFLAGS_NODIST
Value of CFLAGS_NODIST variable passed to the
./configure
script.New in version 3.5.
- BASECFLAGS
- Base compiler flags.
- OPT
- Optimization flags.
- CFLAGS_ALIASING
Strict or non-strict aliasing flags used to compile
Python/dtoa.c
.New in version 3.7.
- CCSHARED
Compiler flags used to build a shared library.
For example,
-fPIC
is used on Linux and on BSD.
- CFLAGSFORSHARED
Extra C flags added for building the interpreter object files.
Default:
$(CCSHARED)
when --enable-shared is used, or an empty string otherwise.
- PY_CFLAGS
- Default:
$(BASECFLAGS) $(OPT) $(CONFIGURE_CFLAGS) $(CFLAGS) $(EXTRA_CFLAGS)
.
- PY_CFLAGS_NODIST
Default:
$(CONFIGURE_CFLAGS_NODIST) $(CFLAGS_NODIST) -I$(srcdir)/Include/internal
.New in version 3.5.
- PY_STDMODULE_CFLAGS
C flags used for building the interpreter object files.
Default:
$(PY_CFLAGS) $(PY_CFLAGS_NODIST) $(PY_CPPFLAGS) $(CFLAGSFORSHARED)
.New in version 3.7.
- PY_CORE_CFLAGS
Default:
$(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE
.New in version 3.2.
- PY_BUILTIN_MODULE_CFLAGS
Compiler flags to build a standard library extension module as a built-in module, like the posix module.
Default:
$(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE_BUILTIN
.New in version 3.8.
- PURIFY
Purify command. Purify is a memory debugger program.
Default: empty string (not used).
3.3.3. Linker flags
- LINKCC
Linker command used to build programs like
python
and_testembed
.Default:
$(PURIFY) $(MAINCC)
.
- CONFIGURE_LDFLAGS
Value of LDFLAGS variable passed to the
./configure
script.Avoid assigning CFLAGS, LDFLAGS, etc. so users can use them on the command line to append to these values without stomping the pre-set values.
New in version 3.2.
- LDFLAGS_NODIST
- LDFLAGS_NODIST is used in the same manner as CFLAGS_NODIST. Use it when a linker flag should not be part of the distutils LDFLAGS once Python is installed (:issue:`35257`).
- CONFIGURE_LDFLAGS_NODIST
Value of LDFLAGS_NODIST variable passed to the
./configure
script.New in version 3.8.
- LDFLAGS
Linker flags, e.g.
-L<lib dir>
if you have libraries in a nonstandard directory<lib dir>
.Both CPPFLAGS and LDFLAGS need to contain the shell’s value for setup.py to be able to build extension modules using the directories specified in the environment variables.
- LIBS
Linker flags to pass libraries to the linker when linking the Python executable.
Example:
-lrt
.
- LDSHARED
Command to build a shared library.
Default:
@LDSHARED@ $(PY_LDFLAGS)
.
- BLDSHARED
Command to build
libpython
shared library.Default:
@BLDSHARED@ $(PY_CORE_LDFLAGS)
.
- PY_LDFLAGS
- Default:
$(CONFIGURE_LDFLAGS) $(LDFLAGS)
.
- PY_LDFLAGS_NODIST
Default:
$(CONFIGURE_LDFLAGS_NODIST) $(LDFLAGS_NODIST)
.New in version 3.8.
- PY_CORE_LDFLAGS
Linker flags used for building the interpreter object files.
New in version 3.8.