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 - _sqliteextension module (default is no) of the- sqlite3module.- See the - sqlite3.Connection.enable_load_extension()method of the- sqlite3module.- New in version 3.6. 
- --enable-big-digits=[15|30]¶
- Define the size in bits of Python - intdigits: 15 or 30 bits.- By default, the digit size is 30. - Define the - PYLONG_BITS_IN_DIGITto- 15or- 30.
- --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 - .exeon Windows and macOS (- python.exeexecutable),- .json Emscripten node,- .htmlon Emscripten browser,- .wasmon WASI, and an empty string on other platforms (- pythonexecutable).- Changed in version 3.11: The default suffix on WASM platform is one of - .js,- .htmlor- .wasm.
- --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- zoneinfomodule.- Default: - /usr/share/zoneinfo:/usr/lib/zoneinfo:/usr/share/lib/zoneinfo:/etc/zoneinfo.- See - os.pathseppath separator.- New in version 3.9. 
- --without-decimal-contextvar¶
- Build the - _decimalextension module using a thread-local context rather than a coroutine-local context (default), see the- decimalmodule.- See - decimal.HAVE_CONTEXTVARand the- contextvarsmodule.- New in version 3.9. 
- --with-dbmliborder=<list of backend names>¶
- Override order to check db backends for the - dbmmodule- 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_LOCALEmacro.- See - PYTHONCOERCECLOCALEand the PEP 538.
- --with-platlibdir=DIRNAME¶
- Python library directory name (default is - lib).- Fedora and SuSE use - lib64on 64-bit platforms.- See - sys.platlibdir.- New in version 3.9. 
- --with-wheel-pkg-dir=PATH¶
- Directory of wheel packages used by the - ensurepipmodule (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 the- ensurepip._bundledpackage.- New in version 3.10. 
- --with-pkg-config=[check|yes|no]¶
- Whether configure should use pkg-config to detect build dependencies. - check(default): pkg-config is optional
- yes: pkg-config is mandatory
- no: configure does not use pkg-config even when present
 - New in version 3.11. 
- --enable-pystats¶
- Turn on internal statistics gathering. - The statistics will be dumped to a arbitrary (probably unique) file in - /tmp/py_stats/, or- C:\temp\py_stats\on Windows.- Use - Tools/scripts/summarize_stats.pyto read the stats.- New in version 3.11. 
3.1.2. WebAssembly Options¶
- --with-emscripten-target=[browser|node]¶
- Set build flavor for - wasm32-emscripten.- browser(default): preload minimal stdlib, default MEMFS.
- node: NODERAWFS and pthread support.
 - New in version 3.11. 
- --enable-wasm-dynamic-linking¶
- Turn on dynamic linking support for WASM. - Dynamic linking enables - dlopen. File size of the executable increases due to limited dead code elimination and additional features.- New in version 3.11. 
- --enable-wasm-pthreads¶
- Turn on pthreads support for WASM. - New in version 3.11. 
3.1.3. Install Options¶
- --prefix=PREFIX¶
- Install architecture-independent files in PREFIX. On Unix, it defaults to - /usr/local.- This value can be retrieved at runtime using - sys.prefix.- As an example, one can use - --prefix="$HOME/.local/"to install a Python in its home directory.
- --exec-prefix=EPREFIX¶
- Install architecture-dependent files in EPREFIX, defaults to - --prefix.- This value can be retrieved at runtime using - sys.exec_prefix.
3.1.4. 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-profdataprogram 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-sharedand GCC is used: add- -fno-semantic-interpositionto the compiler and linker flags.- New in version 3.6. - Changed in version 3.10: Use - -fno-semantic-interpositionon 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=[full|thin|no|yes]¶
- Enable Link Time Optimization (LTO) in any build (disabled by default). - The C compiler Clang requires - llvm-arfor LTO (- aron macOS), as well as an LTO-aware linker (- ld.goldor- lld).- New in version 3.6. - New in version 3.11: To use ThinLTO feature, use - --with-lto=thinon Clang.
- --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 - PYTHONMALLOCenvironment 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_STRINGSmacro.- See the - PyDoc_STRVAR()macro.
- --enable-profiling¶
- Enable C-level code profiling with - gprof(disabled by default).
3.1.5. 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 - warningsmodule.
- Add - dto- sys.abiflags.
- Add - sys.gettotalrefcount()function.
- Add - -X showrefcountcommand line option.
- Add - PYTHONTHREADDEBUGenvironment variable.
- Add support for the - __lltrace__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_DEBUGand- Py_REF_DEBUGmacros.
- Add runtime checks: code surrounded by - #ifdef Py_DEBUGand- #endif. Enable- assert(...)and- _PyObject_ASSERT(...)assertions: don’t set the- NDEBUGmacro (see also the- --with-assertionsconfigure 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. 
- Check that deallocator functions don’t change the current exception. 
- 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.6. Debug options¶
- --with-pydebug¶
- Build Python in debug mode: define the - Py_DEBUGmacro (disabled by default).
- --with-trace-refs¶
- Enable tracing references for debugging purpose (disabled by default). - Effects: - Define the - Py_TRACE_REFSmacro.
- Add - sys.getobjects()function.
- Add - PYTHONDUMPREFSenvironment variable.
 - This build is not ABI compatible with release build (default build) or debug build ( - Py_DEBUGand- Py_REF_DEBUGmacros).- New in version 3.8. 
- --with-assertions¶
- Build with C assertions enabled (default is no): - assert(...);and- _PyObject_ASSERT(...);.- If set, the - NDEBUGmacro is not defined in the- OPTcompiler variable.- See also the - --with-pydebugoption (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.7. Linker options¶
- Enable building a shared Python library: - libpython(default is no).
- --without-static-libpython¶
- Do not build - libpythonMAJOR.MINOR.aand do not install- python.o(built and enabled by default).- New in version 3.10. 
3.1.8. Libraries options¶
- --with-libs='lib1 ...'¶
- Link against additional libraries (default is no). 
- --with-system-expat¶
- Build the - pyexpatmodule using an installed- expatlibrary (default is no).
- --with-system-ffi¶
- Build the - _ctypesextension module using an installed- ffilibrary, see the- ctypesmodule (default is system-dependent).
- --with-system-libmpdec¶
- Build the - _decimalextension module using an installed- mpdeclibrary, see the- decimalmodule (default is no).- New in version 3.3. 
- --with-readline=editline¶
- Use - editlinelibrary for backend of the- readlinemodule.- Define the - WITH_EDITLINEmacro.- New in version 3.10. 
- --without-readline¶
- Don’t build the - readlinemodule (built by default).- Don’t define the - HAVE_LIBREADLINEmacro.- New in version 3.10. 
- --with-libm=STRING¶
- Override - libmmath library to STRING (default is system-dependent).
- --with-libc=STRING¶
- Override - libcC 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-openssland- pkg-config;
- DIR: set an explicit rpath. 
 - New in version 3.10. 
3.1.9. Security Options¶
- --with-hash-algorithm=[fnv|siphash13|siphash24]¶
- Select hash algorithm for use in - Python/pyhash.c:- siphash13(default);
- siphash24;
- fnv.
 - New in version 3.4. - New in version 3.11: - siphash13is added and it is the new default.
- --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 - sslmodule.- New in version 3.7. - Changed in version 3.10: The settings - pythonand STRING also set TLS 1.2 as minimum protocol version.
3.1.10. 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-universalsdkis 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-frameworkis set (default:- Python).
3.1.11. Cross Compiling Options¶
Cross compiling, also known as cross building, can be used to build Python for another CPU architecture or platform. Cross compiling requires a Python interpreter for the build platform. The version of the build Python must match the version of the cross compiled host Python.
- --build=BUILD¶
- configure for building on BUILD, usually guessed by config.guess. 
- --host=HOST¶
- cross-compile to build programs to run on HOST (target platform) 
- --with-build-python=path/to/python¶
- path to build - pythonbinary for cross compiling- New in version 3.11. 
- CONFIG_SITE=file¶
- An environment variable that points to a file with configure overrides. - Example config.site file: - # config.site-aarch64 ac_cv_buggy_getaddrinfo=no ac_cv_file__dev_ptmx=yes ac_cv_file__dev_ptc=no 
Cross compiling example:
CONFIG_SITE=config.site-aarch64 ../configure \
    --build=x86_64-pc-linux-gnu \
    --host=aarch64-unknown-linux-gnu \
    --with-build-python=../x86_64/python
3.2. Python Build System¶
3.2.1. Main files of the build system¶
- configure.ac=>- configure;
- Makefile.pre.in=>- Makefile(created by- configure);
- pyconfig.h(created by- configure);
- Modules/Setup: C extensions built by the Makefile using- Module/makesetupshell script;
- setup.py: C extensions built using the- distutilsmodule.
3.2.2. Main build steps¶
- C files ( - .c) are built as object files (- .o).
- A static - libpythonlibrary (- .a) is created from objects files.
- python.oand the static- libpythonlibrary are linked into the final- pythonprogram.
- C extensions are built by the Makefile (see - Modules/Setup) and- python setup.py build.
3.2.3. Main Makefile targets¶
- make: Build Python with the standard library.
- make platform:: build the- pythonprogram, 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-optimizationsoption to make this the default target of the- makecommand (- make allor just- make).
- make buildbottest: Build Python and run the Python test suite, the same way than buildbots test Python. Set- TESTTIMEOUTvariable (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-namesand- autoconfmust be run separately for the remaining generated files.
- make clean: Remove built files.
- make distclean: Same than- make 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 extensions 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_DATA() and
PyMODINIT_FUNC macros of Include/pyport.h are defined
differently depending if the Py_BUILD_CORE_MODULE macro is defined:
- Use - Py_EXPORTED_SYMBOLif the- Py_BUILD_CORE_MODULEis defined
- Use - Py_IMPORTED_SYMBOLotherwise.
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 - CPPFLAGSvariable passed to the- ./configurescript.- New in version 3.6. 
- CPPFLAGS¶
- (Objective) C/C++ preprocessor flags, e.g. - -Iinclude_dirif you have headers in a nonstandard directory include_dir.- Both - CPPFLAGSand- LDFLAGSneed 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 like- python.- Variable set by the - --with-cxx-mainoption of the configure script.- Default: - $(CC).
- CXX¶
- C++ compiler command. - Used if the - --with-cxx-mainoption is used.- Example: - g++ -pthread.
- CFLAGS¶
- C compiler flags. 
- CFLAGS_NODIST¶
- CFLAGS_NODISTis used for building the interpreter and stdlib C extensions. Use it when a compiler flag should not be part of the distutils- CFLAGSonce Python is installed (bpo-21121).- In particular, - CFLAGSshould not contain:- the compiler flag - -I(for setting the search path for include files). The- -Iflags are processed from left to right, and any flags in- CFLAGSwould take precedence over user- and package-supplied- -Iflags.
- hardening flags such as - -Werrorbecause distributions cannot control whether packages installed by users conform to such heightened standards.
 - New in version 3.5. 
- EXTRA_CFLAGS¶
- Extra C compiler flags. 
- CONFIGURE_CFLAGS_NODIST¶
- Value of - CFLAGS_NODISTvariable passed to the- ./configurescript.- 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, - -fPICis used on Linux and on BSD.
- CFLAGSFORSHARED¶
- Extra C flags added for building the interpreter object files. - Default: - $(CCSHARED)when- --enable-sharedis 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 - posixmodule.- 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 - pythonand- _testembed.- Default: - $(PURIFY) $(MAINCC).
- CONFIGURE_LDFLAGS¶
- Value of - LDFLAGSvariable passed to the- ./configurescript.- 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_NODISTis used in the same manner as- CFLAGS_NODIST. Use it when a linker flag should not be part of the distutils- LDFLAGSonce Python is installed (bpo-35257).- In particular, - LDFLAGSshould not contain:- the compiler flag - -L(for setting the search path for libraries). The- -Lflags are processed from left to right, and any flags in- LDFLAGSwould take precedence over user- and package-supplied- -Lflags.
 
- CONFIGURE_LDFLAGS_NODIST¶
- Value of - LDFLAGS_NODISTvariable passed to the- ./configurescript.- New in version 3.8. 
- LDFLAGS¶
- Linker flags, e.g. - -Llib_dirif you have libraries in a nonstandard directory lib_dir.- Both - CPPFLAGSand- LDFLAGSneed 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 - libpythonshared 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.