1**************** 2Configure Python 3**************** 4 5.. highlight:: sh 6 7Build Requirements 8================== 9 10Features and minimum versions required to build CPython: 11 12* A `C11 <https://en.cppreference.com/w/c/11>`_ compiler. `Optional C11 13 features 14 <https://en.wikipedia.org/wiki/C11_(C_standard_revision)#Optional_features>`_ 15 are not required. 16 17* On Windows, Microsoft Visual Studio 2017 or later is required. 18 19* Support for `IEEE 754 <https://en.wikipedia.org/wiki/IEEE_754>`_ 20 floating-point numbers and `floating-point Not-a-Number (NaN) 21 <https://en.wikipedia.org/wiki/NaN#Floating_point>`_. 22 23* Support for threads. 24 25* OpenSSL 1.1.1 is the minimum version and OpenSSL 3.0.9 is the recommended 26 minimum version for the :mod:`ssl` and :mod:`hashlib` extension modules. 27 28* SQLite 3.15.2 for the :mod:`sqlite3` extension module. 29 30* Tcl/Tk 8.5.12 for the :mod:`tkinter` module. 31 32* Autoconf 2.71 and aclocal 1.16.5 are required to regenerate the 33 :file:`configure` script. 34 35.. versionchanged:: 3.1 36 Tcl/Tk version 8.3.1 is now required. 37 38.. versionchanged:: 3.5 39 On Windows, Visual Studio 2015 or later is now required. 40 Tcl/Tk version 8.4 is now required. 41 42.. versionchanged:: 3.6 43 Selected C99 features are now required, like ``<stdint.h>`` and ``static 44 inline`` functions. 45 46.. versionchanged:: 3.7 47 Thread support and OpenSSL 1.0.2 are now required. 48 49.. versionchanged:: 3.10 50 OpenSSL 1.1.1 is now required. 51 Require SQLite 3.7.15. 52 53.. versionchanged:: 3.11 54 C11 compiler, IEEE 754 and NaN support are now required. 55 On Windows, Visual Studio 2017 or later is required. 56 Tcl/Tk version 8.5.12 is now required for the :mod:`tkinter` module. 57 58.. versionchanged:: 3.13 59 Autoconf 2.71, aclocal 1.16.5 and SQLite 3.15.2 are now required. 60 61See also :pep:`7` "Style Guide for C Code" and :pep:`11` "CPython platform 62support". 63 64 65Generated files 66=============== 67 68To reduce build dependencies, Python source code contains multiple generated 69files. Commands to regenerate all generated files:: 70 71 make regen-all 72 make regen-stdlib-module-names 73 make regen-limited-abi 74 make regen-configure 75 76The ``Makefile.pre.in`` file documents generated files, their inputs, and tools used 77to regenerate them. Search for ``regen-*`` make targets. 78 79configure script 80---------------- 81 82The ``make regen-configure`` command regenerates the ``aclocal.m4`` file and 83the ``configure`` script using the ``Tools/build/regen-configure.sh`` shell 84script which uses an Ubuntu container to get the same tools versions and have a 85reproducible output. 86 87The container is optional, the following command can be run locally:: 88 89 autoreconf -ivf -Werror 90 91The generated files can change depending on the exact ``autoconf-archive``, 92``aclocal`` and ``pkg-config`` versions. 93 94 95.. _configure-options: 96 97Configure Options 98================= 99 100List all :file:`configure` script options using:: 101 102 ./configure --help 103 104See also the :file:`Misc/SpecialBuilds.txt` in the Python source distribution. 105 106General Options 107--------------- 108 109.. option:: --enable-loadable-sqlite-extensions 110 111 Support loadable extensions in the :mod:`!_sqlite` extension module (default 112 is no) of the :mod:`sqlite3` module. 113 114 See the :meth:`sqlite3.Connection.enable_load_extension` method of the 115 :mod:`sqlite3` module. 116 117 .. versionadded:: 3.6 118 119.. option:: --disable-ipv6 120 121 Disable IPv6 support (enabled by default if supported), see the 122 :mod:`socket` module. 123 124.. option:: --enable-big-digits=[15|30] 125 126 Define the size in bits of Python :class:`int` digits: 15 or 30 bits. 127 128 By default, the digit size is 30. 129 130 Define the ``PYLONG_BITS_IN_DIGIT`` to ``15`` or ``30``. 131 132 See :data:`sys.int_info.bits_per_digit <sys.int_info>`. 133 134.. option:: --with-suffix=SUFFIX 135 136 Set the Python executable suffix to *SUFFIX*. 137 138 The default suffix is ``.exe`` on Windows and macOS (``python.exe`` 139 executable), ``.js`` on Emscripten node, ``.html`` on Emscripten browser, 140 ``.wasm`` on WASI, and an empty string on other platforms (``python`` 141 executable). 142 143 .. versionchanged:: 3.11 144 The default suffix on WASM platform is one of ``.js``, ``.html`` 145 or ``.wasm``. 146 147.. option:: --with-tzpath=<list of absolute paths separated by pathsep> 148 149 Select the default time zone search path for :const:`zoneinfo.TZPATH`. 150 See the :ref:`Compile-time configuration 151 <zoneinfo_data_compile_time_config>` of the :mod:`zoneinfo` module. 152 153 Default: ``/usr/share/zoneinfo:/usr/lib/zoneinfo:/usr/share/lib/zoneinfo:/etc/zoneinfo``. 154 155 See :data:`os.pathsep` path separator. 156 157 .. versionadded:: 3.9 158 159.. option:: --without-decimal-contextvar 160 161 Build the ``_decimal`` extension module using a thread-local context rather 162 than a coroutine-local context (default), see the :mod:`decimal` module. 163 164 See :const:`decimal.HAVE_CONTEXTVAR` and the :mod:`contextvars` module. 165 166 .. versionadded:: 3.9 167 168.. option:: --with-dbmliborder=<list of backend names> 169 170 Override order to check db backends for the :mod:`dbm` module 171 172 A valid value is a colon (``:``) separated string with the backend names: 173 174 * ``ndbm``; 175 * ``gdbm``; 176 * ``bdb``. 177 178.. option:: --without-c-locale-coercion 179 180 Disable C locale coercion to a UTF-8 based locale (enabled by default). 181 182 Don't define the ``PY_COERCE_C_LOCALE`` macro. 183 184 See :envvar:`PYTHONCOERCECLOCALE` and the :pep:`538`. 185 186.. option:: --without-freelists 187 188 Disable all freelists except the empty tuple singleton. 189 190 .. versionadded:: 3.11 191 192.. option:: --with-platlibdir=DIRNAME 193 194 Python library directory name (default is ``lib``). 195 196 Fedora and SuSE use ``lib64`` on 64-bit platforms. 197 198 See :data:`sys.platlibdir`. 199 200 .. versionadded:: 3.9 201 202.. option:: --with-wheel-pkg-dir=PATH 203 204 Directory of wheel packages used by the :mod:`ensurepip` module 205 (none by default). 206 207 Some Linux distribution packaging policies recommend against bundling 208 dependencies. For example, Fedora installs wheel packages in the 209 ``/usr/share/python-wheels/`` directory and don't install the 210 :mod:`!ensurepip._bundled` package. 211 212 .. versionadded:: 3.10 213 214.. option:: --with-pkg-config=[check|yes|no] 215 216 Whether configure should use :program:`pkg-config` to detect build 217 dependencies. 218 219 * ``check`` (default): :program:`pkg-config` is optional 220 * ``yes``: :program:`pkg-config` is mandatory 221 * ``no``: configure does not use :program:`pkg-config` even when present 222 223 .. versionadded:: 3.11 224 225.. option:: --enable-pystats 226 227 Turn on internal Python performance statistics gathering. 228 229 By default, statistics gathering is off. Use ``python3 -X pystats`` command 230 or set ``PYTHONSTATS=1`` environment variable to turn on statistics 231 gathering at Python startup. 232 233 At Python exit, dump statistics if statistics gathering was on and not 234 cleared. 235 236 Effects: 237 238 * Add :option:`-X pystats <-X>` command line option. 239 * Add :envvar:`!PYTHONSTATS` environment variable. 240 * Define the ``Py_STATS`` macro. 241 * Add functions to the :mod:`sys` module: 242 243 * :func:`!sys._stats_on`: Turns on statistics gathering. 244 * :func:`!sys._stats_off`: Turns off statistics gathering. 245 * :func:`!sys._stats_clear`: Clears the statistics. 246 * :func:`!sys._stats_dump`: Dump statistics to file, and clears the statistics. 247 248 The statistics will be dumped to a arbitrary (probably unique) file in 249 ``/tmp/py_stats/`` (Unix) or ``C:\temp\py_stats\`` (Windows). If that 250 directory does not exist, results will be printed on stderr. 251 252 Use ``Tools/scripts/summarize_stats.py`` to read the stats. 253 254 Statistics: 255 256 * Opcode: 257 258 * Specialization: success, failure, hit, deferred, miss, deopt, failures; 259 * Execution count; 260 * Pair count. 261 262 * Call: 263 264 * Inlined Python calls; 265 * PyEval calls; 266 * Frames pushed; 267 * Frame object created; 268 * Eval calls: vector, generator, legacy, function VECTORCALL, build class, 269 slot, function "ex", API, method. 270 271 * Object: 272 273 * incref and decref; 274 * interpreter incref and decref; 275 * allocations: all, 512 bytes, 4 kiB, big; 276 * free; 277 * to/from free lists; 278 * dictionary materialized/dematerialized; 279 * type cache; 280 * optimization attempts; 281 * optimization traces created/executed; 282 * uops executed. 283 284 * Garbage collector: 285 286 * Garbage collections; 287 * Objects visited; 288 * Objects collected. 289 290 .. versionadded:: 3.11 291 292.. _free-threading-build: 293 294.. option:: --disable-gil 295 296 Enables **experimental** support for running Python without the 297 :term:`global interpreter lock` (GIL): free threading build. 298 299 Defines the ``Py_GIL_DISABLED`` macro and adds ``"t"`` to 300 :data:`sys.abiflags`. 301 302 See :ref:`whatsnew313-free-threaded-cpython` for more detail. 303 304 .. versionadded:: 3.13 305 306.. option:: --enable-experimental-jit=[no|yes|yes-off|interpreter] 307 308 Indicate how to integrate the :ref:`JIT compiler <whatsnew313-jit-compiler>`. 309 310 * ``no`` - build the interpreter without the JIT. 311 * ``yes`` - build the interpreter with the JIT. 312 * ``yes-off`` - build the interpreter with the JIT but disable it by default. 313 * ``interpreter`` - build the interpreter without the JIT, but with the tier 2 enabled interpreter. 314 315 By convention, ``--enable-experimental-jit`` is a shorthand for ``--enable-experimental-jit=yes``. 316 317 .. versionadded:: 3.13 318 319.. option:: PKG_CONFIG 320 321 Path to ``pkg-config`` utility. 322 323.. option:: PKG_CONFIG_LIBDIR 324.. option:: PKG_CONFIG_PATH 325 326 ``pkg-config`` options. 327 328 329C compiler options 330------------------ 331 332.. option:: CC 333 334 C compiler command. 335 336.. option:: CFLAGS 337 338 C compiler flags. 339 340.. option:: CPP 341 342 C preprocessor command. 343 344.. option:: CPPFLAGS 345 346 C preprocessor flags, e.g. :samp:`-I{include_dir}`. 347 348 349Linker options 350-------------- 351 352.. option:: LDFLAGS 353 354 Linker flags, e.g. :samp:`-L{library_directory}`. 355 356.. option:: LIBS 357 358 Libraries to pass to the linker, e.g. :samp:`-l{library}`. 359 360.. option:: MACHDEP 361 362 Name for machine-dependent library files. 363 364 365Options for third-party dependencies 366------------------------------------ 367 368.. versionadded:: 3.11 369 370.. option:: BZIP2_CFLAGS 371.. option:: BZIP2_LIBS 372 373 C compiler and linker flags to link Python to ``libbz2``, used by :mod:`bz2` 374 module, overriding ``pkg-config``. 375 376.. option:: CURSES_CFLAGS 377.. option:: CURSES_LIBS 378 379 C compiler and linker flags for ``libncurses`` or ``libncursesw``, used by 380 :mod:`curses` module, overriding ``pkg-config``. 381 382.. option:: GDBM_CFLAGS 383.. option:: GDBM_LIBS 384 385 C compiler and linker flags for ``gdbm``. 386 387.. option:: LIBB2_CFLAGS 388.. option:: LIBB2_LIBS 389 390 C compiler and linker flags for ``libb2`` (:ref:`BLAKE2 <hashlib-blake2>`), 391 used by :mod:`hashlib` module, overriding ``pkg-config``. 392 393.. option:: LIBEDIT_CFLAGS 394.. option:: LIBEDIT_LIBS 395 396 C compiler and linker flags for ``libedit``, used by :mod:`readline` module, 397 overriding ``pkg-config``. 398 399.. option:: LIBFFI_CFLAGS 400.. option:: LIBFFI_LIBS 401 402 C compiler and linker flags for ``libffi``, used by :mod:`ctypes` module, 403 overriding ``pkg-config``. 404 405.. option:: LIBMPDEC_CFLAGS 406.. option:: LIBMPDEC_LIBS 407 408 C compiler and linker flags for ``libmpdec``, used by :mod:`decimal` module, 409 overriding ``pkg-config``. 410 411 .. note:: 412 413 These environment variables have no effect unless 414 :option:`--with-system-libmpdec` is specified. 415 416.. option:: LIBLZMA_CFLAGS 417.. option:: LIBLZMA_LIBS 418 419 C compiler and linker flags for ``liblzma``, used by :mod:`lzma` module, 420 overriding ``pkg-config``. 421 422.. option:: LIBREADLINE_CFLAGS 423.. option:: LIBREADLINE_LIBS 424 425 C compiler and linker flags for ``libreadline``, used by :mod:`readline` 426 module, overriding ``pkg-config``. 427 428.. option:: LIBSQLITE3_CFLAGS 429.. option:: LIBSQLITE3_LIBS 430 431 C compiler and linker flags for ``libsqlite3``, used by :mod:`sqlite3` 432 module, overriding ``pkg-config``. 433 434.. option:: LIBUUID_CFLAGS 435.. option:: LIBUUID_LIBS 436 437 C compiler and linker flags for ``libuuid``, used by :mod:`uuid` module, 438 overriding ``pkg-config``. 439 440.. option:: PANEL_CFLAGS 441.. option:: PANEL_LIBS 442 443 C compiler and linker flags for PANEL, overriding ``pkg-config``. 444 445 C compiler and linker flags for ``libpanel`` or ``libpanelw``, used by 446 :mod:`curses.panel` module, overriding ``pkg-config``. 447 448.. option:: TCLTK_CFLAGS 449.. option:: TCLTK_LIBS 450 451 C compiler and linker flags for TCLTK, overriding ``pkg-config``. 452 453.. option:: ZLIB_CFLAGS 454.. option:: ZLIB_LIBS 455 456 C compiler and linker flags for ``libzlib``, used by :mod:`gzip` module, 457 overriding ``pkg-config``. 458 459 460WebAssembly Options 461------------------- 462 463.. option:: --with-emscripten-target=[browser|node] 464 465 Set build flavor for ``wasm32-emscripten``. 466 467 * ``browser`` (default): preload minimal stdlib, default MEMFS. 468 * ``node``: NODERAWFS and pthread support. 469 470 .. versionadded:: 3.11 471 472.. option:: --enable-wasm-dynamic-linking 473 474 Turn on dynamic linking support for WASM. 475 476 Dynamic linking enables ``dlopen``. File size of the executable 477 increases due to limited dead code elimination and additional features. 478 479 .. versionadded:: 3.11 480 481.. option:: --enable-wasm-pthreads 482 483 Turn on pthreads support for WASM. 484 485 .. versionadded:: 3.11 486 487 488Install Options 489--------------- 490 491.. option:: --prefix=PREFIX 492 493 Install architecture-independent files in PREFIX. On Unix, it 494 defaults to :file:`/usr/local`. 495 496 This value can be retrieved at runtime using :data:`sys.prefix`. 497 498 As an example, one can use ``--prefix="$HOME/.local/"`` to install 499 a Python in its home directory. 500 501.. option:: --exec-prefix=EPREFIX 502 503 Install architecture-dependent files in EPREFIX, defaults to :option:`--prefix`. 504 505 This value can be retrieved at runtime using :data:`sys.exec_prefix`. 506 507.. option:: --disable-test-modules 508 509 Don't build nor install test modules, like the :mod:`test` package or the 510 :mod:`!_testcapi` extension module (built and installed by default). 511 512 .. versionadded:: 3.10 513 514.. option:: --with-ensurepip=[upgrade|install|no] 515 516 Select the :mod:`ensurepip` command run on Python installation: 517 518 * ``upgrade`` (default): run ``python -m ensurepip --altinstall --upgrade`` 519 command. 520 * ``install``: run ``python -m ensurepip --altinstall`` command; 521 * ``no``: don't run ensurepip; 522 523 .. versionadded:: 3.6 524 525 526Performance options 527------------------- 528 529Configuring Python using ``--enable-optimizations --with-lto`` (PGO + LTO) is 530recommended for best performance. The experimental ``--enable-bolt`` flag can 531also be used to improve performance. 532 533.. option:: --enable-optimizations 534 535 Enable Profile Guided Optimization (PGO) using :envvar:`PROFILE_TASK` 536 (disabled by default). 537 538 The C compiler Clang requires ``llvm-profdata`` program for PGO. On 539 macOS, GCC also requires it: GCC is just an alias to Clang on macOS. 540 541 Disable also semantic interposition in libpython if ``--enable-shared`` and 542 GCC is used: add ``-fno-semantic-interposition`` to the compiler and linker 543 flags. 544 545 .. note:: 546 547 During the build, you may encounter compiler warnings about 548 profile data not being available for some source files. 549 These warnings are harmless, as only a subset of the code is exercised 550 during profile data acquisition. 551 To disable these warnings on Clang, manually suppress them by adding 552 ``-Wno-profile-instr-unprofiled`` to :envvar:`CFLAGS`. 553 554 .. versionadded:: 3.6 555 556 .. versionchanged:: 3.10 557 Use ``-fno-semantic-interposition`` on GCC. 558 559.. envvar:: PROFILE_TASK 560 561 Environment variable used in the Makefile: Python command line arguments for 562 the PGO generation task. 563 564 Default: ``-m test --pgo --timeout=$(TESTTIMEOUT)``. 565 566 .. versionadded:: 3.8 567 568 .. versionchanged:: 3.13 569 Task failure is no longer ignored silently. 570 571.. option:: --with-lto=[full|thin|no|yes] 572 573 Enable Link Time Optimization (LTO) in any build (disabled by default). 574 575 The C compiler Clang requires ``llvm-ar`` for LTO (``ar`` on macOS), as well 576 as an LTO-aware linker (``ld.gold`` or ``lld``). 577 578 .. versionadded:: 3.6 579 580 .. versionadded:: 3.11 581 To use ThinLTO feature, use ``--with-lto=thin`` on Clang. 582 583 .. versionchanged:: 3.12 584 Use ThinLTO as the default optimization policy on Clang if the compiler accepts the flag. 585 586.. option:: --enable-bolt 587 588 Enable usage of the `BOLT post-link binary optimizer 589 <https://github.com/llvm/llvm-project/tree/main/bolt>`_ (disabled by 590 default). 591 592 BOLT is part of the LLVM project but is not always included in their binary 593 distributions. This flag requires that ``llvm-bolt`` and ``merge-fdata`` 594 are available. 595 596 BOLT is still a fairly new project so this flag should be considered 597 experimental for now. Because this tool operates on machine code its success 598 is dependent on a combination of the build environment + the other 599 optimization configure args + the CPU architecture, and not all combinations 600 are supported. 601 BOLT versions before LLVM 16 are known to crash BOLT under some scenarios. 602 Use of LLVM 16 or newer for BOLT optimization is strongly encouraged. 603 604 The :envvar:`!BOLT_INSTRUMENT_FLAGS` and :envvar:`!BOLT_APPLY_FLAGS` 605 :program:`configure` variables can be defined to override the default set of 606 arguments for :program:`llvm-bolt` to instrument and apply BOLT data to 607 binaries, respectively. 608 609 .. versionadded:: 3.12 610 611.. option:: BOLT_APPLY_FLAGS 612 613 Arguments to ``llvm-bolt`` when creating a `BOLT optimized binary 614 <https://github.com/facebookarchive/BOLT>`_. 615 616 .. versionadded:: 3.12 617 618.. option:: BOLT_INSTRUMENT_FLAGS 619 620 Arguments to ``llvm-bolt`` when instrumenting binaries. 621 622 .. versionadded:: 3.12 623 624.. option:: --with-computed-gotos 625 626 Enable computed gotos in evaluation loop (enabled by default on supported 627 compilers). 628 629.. option:: --without-mimalloc 630 631 Disable the fast :ref:`mimalloc <mimalloc>` allocator 632 (enabled by default). 633 634 See also :envvar:`PYTHONMALLOC` environment variable. 635 636.. option:: --without-pymalloc 637 638 Disable the specialized Python memory allocator :ref:`pymalloc <pymalloc>` 639 (enabled by default). 640 641 See also :envvar:`PYTHONMALLOC` environment variable. 642 643.. option:: --without-doc-strings 644 645 Disable static documentation strings to reduce the memory footprint (enabled 646 by default). Documentation strings defined in Python are not affected. 647 648 Don't define the ``WITH_DOC_STRINGS`` macro. 649 650 See the ``PyDoc_STRVAR()`` macro. 651 652.. option:: --enable-profiling 653 654 Enable C-level code profiling with ``gprof`` (disabled by default). 655 656.. option:: --with-strict-overflow 657 658 Add ``-fstrict-overflow`` to the C compiler flags (by default we add 659 ``-fno-strict-overflow`` instead). 660 661 662.. _debug-build: 663 664Python Debug Build 665------------------ 666 667A debug build is Python built with the :option:`--with-pydebug` configure 668option. 669 670Effects of a debug build: 671 672* Display all warnings by default: the list of default warning filters is empty 673 in the :mod:`warnings` module. 674* Add ``d`` to :data:`sys.abiflags`. 675* Add :func:`!sys.gettotalrefcount` function. 676* Add :option:`-X showrefcount <-X>` command line option. 677* Add :option:`-d` command line option and :envvar:`PYTHONDEBUG` environment 678 variable to debug the parser. 679* Add support for the ``__lltrace__`` variable: enable low-level tracing in the 680 bytecode evaluation loop if the variable is defined. 681* Install :ref:`debug hooks on memory allocators <default-memory-allocators>` 682 to detect buffer overflow and other memory errors. 683* Define ``Py_DEBUG`` and ``Py_REF_DEBUG`` macros. 684* Add runtime checks: code surrounded by ``#ifdef Py_DEBUG`` and ``#endif``. 685 Enable ``assert(...)`` and ``_PyObject_ASSERT(...)`` assertions: don't set 686 the ``NDEBUG`` macro (see also the :option:`--with-assertions` configure 687 option). Main runtime checks: 688 689 * Add sanity checks on the function arguments. 690 * Unicode and int objects are created with their memory filled with a pattern 691 to detect usage of uninitialized objects. 692 * Ensure that functions which can clear or replace the current exception are 693 not called with an exception raised. 694 * Check that deallocator functions don't change the current exception. 695 * The garbage collector (:func:`gc.collect` function) runs some basic checks 696 on objects consistency. 697 * The :c:macro:`!Py_SAFE_DOWNCAST()` macro checks for integer underflow and 698 overflow when downcasting from wide types to narrow types. 699 700See also the :ref:`Python Development Mode <devmode>` and the 701:option:`--with-trace-refs` configure option. 702 703.. versionchanged:: 3.8 704 Release builds and debug builds are now ABI compatible: defining the 705 ``Py_DEBUG`` macro no longer implies the ``Py_TRACE_REFS`` macro (see the 706 :option:`--with-trace-refs` option). 707 708 709Debug options 710------------- 711 712.. option:: --with-pydebug 713 714 :ref:`Build Python in debug mode <debug-build>`: define the ``Py_DEBUG`` 715 macro (disabled by default). 716 717.. option:: --with-trace-refs 718 719 Enable tracing references for debugging purpose (disabled by default). 720 721 Effects: 722 723 * Define the ``Py_TRACE_REFS`` macro. 724 * Add :func:`sys.getobjects` function. 725 * Add :envvar:`PYTHONDUMPREFS` environment variable. 726 727 The :envvar:`PYTHONDUMPREFS` environment variable can be used to dump 728 objects and reference counts still alive at Python exit. 729 730 :ref:`Statically allocated objects <static-types>` are not traced. 731 732 .. versionadded:: 3.8 733 734 .. versionchanged:: 3.13 735 This build is now ABI compatible with release build and :ref:`debug build 736 <debug-build>`. 737 738.. option:: --with-assertions 739 740 Build with C assertions enabled (default is no): ``assert(...);`` and 741 ``_PyObject_ASSERT(...);``. 742 743 If set, the ``NDEBUG`` macro is not defined in the :envvar:`OPT` compiler 744 variable. 745 746 See also the :option:`--with-pydebug` option (:ref:`debug build 747 <debug-build>`) which also enables assertions. 748 749 .. versionadded:: 3.6 750 751.. option:: --with-valgrind 752 753 Enable Valgrind support (default is no). 754 755.. option:: --with-dtrace 756 757 Enable DTrace support (default is no). 758 759 See :ref:`Instrumenting CPython with DTrace and SystemTap 760 <instrumentation>`. 761 762 .. versionadded:: 3.6 763 764.. option:: --with-address-sanitizer 765 766 Enable AddressSanitizer memory error detector, ``asan`` (default is no). 767 768 .. versionadded:: 3.6 769 770.. option:: --with-memory-sanitizer 771 772 Enable MemorySanitizer allocation error detector, ``msan`` (default is no). 773 774 .. versionadded:: 3.6 775 776.. option:: --with-undefined-behavior-sanitizer 777 778 Enable UndefinedBehaviorSanitizer undefined behaviour detector, ``ubsan`` 779 (default is no). 780 781 .. versionadded:: 3.6 782 783.. option:: --with-thread-sanitizer 784 785 Enable ThreadSanitizer data race detector, ``tsan`` 786 (default is no). 787 788 .. versionadded:: 3.13 789 790 791Linker options 792-------------- 793 794.. option:: --enable-shared 795 796 Enable building a shared Python library: ``libpython`` (default is no). 797 798.. option:: --without-static-libpython 799 800 Do not build ``libpythonMAJOR.MINOR.a`` and do not install ``python.o`` 801 (built and enabled by default). 802 803 .. versionadded:: 3.10 804 805 806Libraries options 807----------------- 808 809.. option:: --with-libs='lib1 ...' 810 811 Link against additional libraries (default is no). 812 813.. option:: --with-system-expat 814 815 Build the :mod:`!pyexpat` module using an installed ``expat`` library 816 (default is no). 817 818.. option:: --with-system-libmpdec 819 820 Build the ``_decimal`` extension module using an installed ``mpdecimal`` 821 library, see the :mod:`decimal` module (default is yes). 822 823 .. versionadded:: 3.3 824 825 .. versionchanged:: 3.13 826 Default to using the installed ``mpdecimal`` library. 827 828 .. deprecated-removed:: 3.13 3.15 829 A copy of the ``mpdecimal`` library sources will no longer be distributed 830 with Python 3.15. 831 832 .. seealso:: :option:`LIBMPDEC_CFLAGS` and :option:`LIBMPDEC_LIBS`. 833 834.. option:: --with-readline=readline|editline 835 836 Designate a backend library for the :mod:`readline` module. 837 838 * readline: Use readline as the backend. 839 * editline: Use editline as the backend. 840 841 .. versionadded:: 3.10 842 843.. option:: --without-readline 844 845 Don't build the :mod:`readline` module (built by default). 846 847 Don't define the ``HAVE_LIBREADLINE`` macro. 848 849 .. versionadded:: 3.10 850 851.. option:: --with-libm=STRING 852 853 Override ``libm`` math library to *STRING* (default is system-dependent). 854 855.. option:: --with-libc=STRING 856 857 Override ``libc`` C library to *STRING* (default is system-dependent). 858 859.. option:: --with-openssl=DIR 860 861 Root of the OpenSSL directory. 862 863 .. versionadded:: 3.7 864 865.. option:: --with-openssl-rpath=[no|auto|DIR] 866 867 Set runtime library directory (rpath) for OpenSSL libraries: 868 869 * ``no`` (default): don't set rpath; 870 * ``auto``: auto-detect rpath from :option:`--with-openssl` and 871 ``pkg-config``; 872 * *DIR*: set an explicit rpath. 873 874 .. versionadded:: 3.10 875 876 877Security Options 878---------------- 879 880.. option:: --with-hash-algorithm=[fnv|siphash13|siphash24] 881 882 Select hash algorithm for use in ``Python/pyhash.c``: 883 884 * ``siphash13`` (default); 885 * ``siphash24``; 886 * ``fnv``. 887 888 .. versionadded:: 3.4 889 890 .. versionadded:: 3.11 891 ``siphash13`` is added and it is the new default. 892 893.. option:: --with-builtin-hashlib-hashes=md5,sha1,sha256,sha512,sha3,blake2 894 895 Built-in hash modules: 896 897 * ``md5``; 898 * ``sha1``; 899 * ``sha256``; 900 * ``sha512``; 901 * ``sha3`` (with shake); 902 * ``blake2``. 903 904 .. versionadded:: 3.9 905 906.. option:: --with-ssl-default-suites=[python|openssl|STRING] 907 908 Override the OpenSSL default cipher suites string: 909 910 * ``python`` (default): use Python's preferred selection; 911 * ``openssl``: leave OpenSSL's defaults untouched; 912 * *STRING*: use a custom string 913 914 See the :mod:`ssl` module. 915 916 .. versionadded:: 3.7 917 918 .. versionchanged:: 3.10 919 920 The settings ``python`` and *STRING* also set TLS 1.2 as minimum 921 protocol version. 922 923macOS Options 924------------- 925 926See :source:`Mac/README.rst`. 927 928.. option:: --enable-universalsdk 929.. option:: --enable-universalsdk=SDKDIR 930 931 Create a universal binary build. *SDKDIR* specifies which macOS SDK should 932 be used to perform the build (default is no). 933 934.. option:: --enable-framework 935.. option:: --enable-framework=INSTALLDIR 936 937 Create a Python.framework rather than a traditional Unix install. Optional 938 *INSTALLDIR* specifies the installation path (default is no). 939 940.. option:: --with-universal-archs=ARCH 941 942 Specify the kind of universal binary that should be created. This option is 943 only valid when :option:`--enable-universalsdk` is set. 944 945 Options: 946 947 * ``universal2``; 948 * ``32-bit``; 949 * ``64-bit``; 950 * ``3-way``; 951 * ``intel``; 952 * ``intel-32``; 953 * ``intel-64``; 954 * ``all``. 955 956.. option:: --with-framework-name=FRAMEWORK 957 958 Specify the name for the python framework on macOS only valid when 959 :option:`--enable-framework` is set (default: ``Python``). 960 961.. option:: --with-app-store-compliance 962.. option:: --with-app-store-compliance=PATCH-FILE 963 964 The Python standard library contains strings that are known to trigger 965 automated inspection tool errors when submitted for distribution by 966 the macOS and iOS App Stores. If enabled, this option will apply the list of 967 patches that are known to correct app store compliance. A custom patch 968 file can also be specified. This option is disabled by default. 969 970 .. versionadded:: 3.13 971 972iOS Options 973----------- 974 975See :source:`iOS/README.rst`. 976 977.. option:: --enable-framework=INSTALLDIR 978 979 Create a Python.framework. Unlike macOS, the *INSTALLDIR* argument 980 specifying the installation path is mandatory. 981 982.. option:: --with-framework-name=FRAMEWORK 983 984 Specify the name for the framework (default: ``Python``). 985 986 987Cross Compiling Options 988----------------------- 989 990Cross compiling, also known as cross building, can be used to build Python 991for another CPU architecture or platform. Cross compiling requires a Python 992interpreter for the build platform. The version of the build Python must match 993the version of the cross compiled host Python. 994 995.. option:: --build=BUILD 996 997 configure for building on BUILD, usually guessed by :program:`config.guess`. 998 999.. option:: --host=HOST 1000 1001 cross-compile to build programs to run on HOST (target platform) 1002 1003.. option:: --with-build-python=path/to/python 1004 1005 path to build ``python`` binary for cross compiling 1006 1007 .. versionadded:: 3.11 1008 1009.. option:: CONFIG_SITE=file 1010 1011 An environment variable that points to a file with configure overrides. 1012 1013 Example *config.site* file: 1014 1015 .. code-block:: ini 1016 1017 # config.site-aarch64 1018 ac_cv_buggy_getaddrinfo=no 1019 ac_cv_file__dev_ptmx=yes 1020 ac_cv_file__dev_ptc=no 1021 1022.. option:: HOSTRUNNER 1023 1024 Program to run CPython for the host platform for cross-compilation. 1025 1026 .. versionadded:: 3.11 1027 1028 1029Cross compiling example:: 1030 1031 CONFIG_SITE=config.site-aarch64 ../configure \ 1032 --build=x86_64-pc-linux-gnu \ 1033 --host=aarch64-unknown-linux-gnu \ 1034 --with-build-python=../x86_64/python 1035 1036 1037Python Build System 1038=================== 1039 1040Main files of the build system 1041------------------------------ 1042 1043* :file:`configure.ac` => :file:`configure`; 1044* :file:`Makefile.pre.in` => :file:`Makefile` (created by :file:`configure`); 1045* :file:`pyconfig.h` (created by :file:`configure`); 1046* :file:`Modules/Setup`: C extensions built by the Makefile using 1047 :file:`Module/makesetup` shell script; 1048 1049Main build steps 1050---------------- 1051 1052* C files (``.c``) are built as object files (``.o``). 1053* A static ``libpython`` library (``.a``) is created from objects files. 1054* ``python.o`` and the static ``libpython`` library are linked into the 1055 final ``python`` program. 1056* C extensions are built by the Makefile (see :file:`Modules/Setup`). 1057 1058Main Makefile targets 1059--------------------- 1060 1061make 1062^^^^ 1063 1064For the most part, when rebuilding after editing some code or 1065refreshing your checkout from upstream, all you need to do is execute 1066``make``, which (per Make's semantics) builds the default target, the 1067first one defined in the Makefile. By tradition (including in the 1068CPython project) this is usually the ``all`` target. The 1069``configure`` script expands an ``autoconf`` variable, 1070``@DEF_MAKE_ALL_RULE@`` to describe precisely which targets ``make 1071all`` will build. The three choices are: 1072 1073* ``profile-opt`` (configured with ``--enable-optimizations``) 1074* ``build_wasm`` (configured with ``--with-emscripten-target``) 1075* ``build_all`` (configured without explicitly using either of the others) 1076 1077Depending on the most recent source file changes, Make will rebuild 1078any targets (object files and executables) deemed out-of-date, 1079including running ``configure`` again if necessary. Source/target 1080dependencies are many and maintained manually however, so Make 1081sometimes doesn't have all the information necessary to correctly 1082detect all targets which need to be rebuilt. Depending on which 1083targets aren't rebuilt, you might experience a number of problems. If 1084you have build or test problems which you can't otherwise explain, 1085``make clean && make`` should work around most dependency problems, at 1086the expense of longer build times. 1087 1088 1089make platform 1090^^^^^^^^^^^^^ 1091 1092Build the ``python`` program, but don't build the standard library 1093extension modules. This generates a file named ``platform`` which 1094contains a single line describing the details of the build platform, 1095e.g., ``macosx-14.3-arm64-3.12`` or ``linux-x86_64-3.13``. 1096 1097 1098make profile-opt 1099^^^^^^^^^^^^^^^^ 1100 1101Build Python using profile-guided optimization (PGO). You can use the 1102configure :option:`--enable-optimizations` option to make this the 1103default target of the ``make`` command (``make all`` or just 1104``make``). 1105 1106 1107 1108make clean 1109^^^^^^^^^^ 1110 1111Remove built files. 1112 1113 1114make distclean 1115^^^^^^^^^^^^^^ 1116 1117In addition to the work done by ``make clean``, remove files 1118created by the configure script. ``configure`` will have to be run 1119before building again. [#]_ 1120 1121 1122make install 1123^^^^^^^^^^^^ 1124 1125Build the ``all`` target and install Python. 1126 1127 1128make test 1129^^^^^^^^^ 1130 1131Build the ``all`` target and run the Python test suite with the 1132``--fast-ci`` option. Variables: 1133 1134* ``TESTOPTS``: additional regrtest command-line options. 1135* ``TESTPYTHONOPTS``: additional Python command-line options. 1136* ``TESTTIMEOUT``: timeout in seconds (default: 10 minutes). 1137 1138 1139make buildbottest 1140^^^^^^^^^^^^^^^^^ 1141 1142This is similar to ``make test``, but uses the ``--slow-ci`` 1143option and default timeout of 20 minutes, instead of ``--fast-ci`` option. 1144 1145 1146make regen-all 1147^^^^^^^^^^^^^^ 1148 1149Regenerate (almost) all generated files. These include (but are not 1150limited to) bytecode cases, and parser generator file. 1151``make regen-stdlib-module-names`` and ``autoconf`` must be run 1152separately for the remaining `generated files <#generated-files>`_. 1153 1154 1155C extensions 1156------------ 1157 1158Some C extensions are built as built-in modules, like the ``sys`` module. 1159They are built with the ``Py_BUILD_CORE_BUILTIN`` macro defined. 1160Built-in modules have no ``__file__`` attribute: 1161 1162.. code-block:: pycon 1163 1164 >>> import sys 1165 >>> sys 1166 <module 'sys' (built-in)> 1167 >>> sys.__file__ 1168 Traceback (most recent call last): 1169 File "<stdin>", line 1, in <module> 1170 AttributeError: module 'sys' has no attribute '__file__' 1171 1172Other C extensions are built as dynamic libraries, like the ``_asyncio`` module. 1173They are built with the ``Py_BUILD_CORE_MODULE`` macro defined. 1174Example on Linux x86-64: 1175 1176.. code-block:: pycon 1177 1178 >>> import _asyncio 1179 >>> _asyncio 1180 <module '_asyncio' from '/usr/lib64/python3.9/lib-dynload/_asyncio.cpython-39-x86_64-linux-gnu.so'> 1181 >>> _asyncio.__file__ 1182 '/usr/lib64/python3.9/lib-dynload/_asyncio.cpython-39-x86_64-linux-gnu.so' 1183 1184:file:`Modules/Setup` is used to generate Makefile targets to build C extensions. 1185At the beginning of the files, C extensions are built as built-in modules. 1186Extensions defined after the ``*shared*`` marker are built as dynamic libraries. 1187 1188The :c:macro:`!PyAPI_FUNC()`, :c:macro:`!PyAPI_DATA()` and 1189:c:macro:`PyMODINIT_FUNC` macros of :file:`Include/exports.h` are defined 1190differently depending if the ``Py_BUILD_CORE_MODULE`` macro is defined: 1191 1192* Use ``Py_EXPORTED_SYMBOL`` if the ``Py_BUILD_CORE_MODULE`` is defined 1193* Use ``Py_IMPORTED_SYMBOL`` otherwise. 1194 1195If the ``Py_BUILD_CORE_BUILTIN`` macro is used by mistake on a C extension 1196built as a shared library, its :samp:`PyInit_{xxx}()` function is not exported, 1197causing an :exc:`ImportError` on import. 1198 1199 1200Compiler and linker flags 1201========================= 1202 1203Options set by the ``./configure`` script and environment variables and used by 1204``Makefile``. 1205 1206Preprocessor flags 1207------------------ 1208 1209.. envvar:: CONFIGURE_CPPFLAGS 1210 1211 Value of :envvar:`CPPFLAGS` variable passed to the ``./configure`` script. 1212 1213 .. versionadded:: 3.6 1214 1215.. envvar:: CPPFLAGS 1216 1217 (Objective) C/C++ preprocessor flags, e.g. :samp:`-I{include_dir}` if you have 1218 headers in a nonstandard directory *include_dir*. 1219 1220 Both :envvar:`CPPFLAGS` and :envvar:`LDFLAGS` need to contain the shell's 1221 value to be able to build extension modules using the 1222 directories specified in the environment variables. 1223 1224.. envvar:: BASECPPFLAGS 1225 1226 .. versionadded:: 3.4 1227 1228.. envvar:: PY_CPPFLAGS 1229 1230 Extra preprocessor flags added for building the interpreter object files. 1231 1232 Default: ``$(BASECPPFLAGS) -I. -I$(srcdir)/Include $(CONFIGURE_CPPFLAGS) $(CPPFLAGS)``. 1233 1234 .. versionadded:: 3.2 1235 1236Compiler flags 1237-------------- 1238 1239.. envvar:: CC 1240 1241 C compiler command. 1242 1243 Example: ``gcc -pthread``. 1244 1245.. envvar:: CXX 1246 1247 C++ compiler command. 1248 1249 Example: ``g++ -pthread``. 1250 1251.. envvar:: CFLAGS 1252 1253 C compiler flags. 1254 1255.. envvar:: CFLAGS_NODIST 1256 1257 :envvar:`CFLAGS_NODIST` is used for building the interpreter and stdlib C 1258 extensions. Use it when a compiler flag should *not* be part of 1259 :envvar:`CFLAGS` once Python is installed (:gh:`65320`). 1260 1261 In particular, :envvar:`CFLAGS` should not contain: 1262 1263 * the compiler flag ``-I`` (for setting the search path for include files). 1264 The ``-I`` flags are processed from left to right, and any flags in 1265 :envvar:`CFLAGS` would take precedence over user- and package-supplied ``-I`` 1266 flags. 1267 1268 * hardening flags such as ``-Werror`` because distributions cannot control 1269 whether packages installed by users conform to such heightened 1270 standards. 1271 1272 .. versionadded:: 3.5 1273 1274.. envvar:: COMPILEALL_OPTS 1275 1276 Options passed to the :mod:`compileall` command line when building PYC files 1277 in ``make install``. Default: ``-j0``. 1278 1279 .. versionadded:: 3.12 1280 1281.. envvar:: EXTRA_CFLAGS 1282 1283 Extra C compiler flags. 1284 1285.. envvar:: CONFIGURE_CFLAGS 1286 1287 Value of :envvar:`CFLAGS` variable passed to the ``./configure`` 1288 script. 1289 1290 .. versionadded:: 3.2 1291 1292.. envvar:: CONFIGURE_CFLAGS_NODIST 1293 1294 Value of :envvar:`CFLAGS_NODIST` variable passed to the ``./configure`` 1295 script. 1296 1297 .. versionadded:: 3.5 1298 1299.. envvar:: BASECFLAGS 1300 1301 Base compiler flags. 1302 1303.. envvar:: OPT 1304 1305 Optimization flags. 1306 1307.. envvar:: CFLAGS_ALIASING 1308 1309 Strict or non-strict aliasing flags used to compile ``Python/dtoa.c``. 1310 1311 .. versionadded:: 3.7 1312 1313.. envvar:: CCSHARED 1314 1315 Compiler flags used to build a shared library. 1316 1317 For example, ``-fPIC`` is used on Linux and on BSD. 1318 1319.. envvar:: CFLAGSFORSHARED 1320 1321 Extra C flags added for building the interpreter object files. 1322 1323 Default: ``$(CCSHARED)`` when :option:`--enable-shared` is used, or an empty 1324 string otherwise. 1325 1326.. envvar:: PY_CFLAGS 1327 1328 Default: ``$(BASECFLAGS) $(OPT) $(CONFIGURE_CFLAGS) $(CFLAGS) $(EXTRA_CFLAGS)``. 1329 1330.. envvar:: PY_CFLAGS_NODIST 1331 1332 Default: ``$(CONFIGURE_CFLAGS_NODIST) $(CFLAGS_NODIST) -I$(srcdir)/Include/internal``. 1333 1334 .. versionadded:: 3.5 1335 1336.. envvar:: PY_STDMODULE_CFLAGS 1337 1338 C flags used for building the interpreter object files. 1339 1340 Default: ``$(PY_CFLAGS) $(PY_CFLAGS_NODIST) $(PY_CPPFLAGS) $(CFLAGSFORSHARED)``. 1341 1342 .. versionadded:: 3.7 1343 1344.. envvar:: PY_CORE_CFLAGS 1345 1346 Default: ``$(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE``. 1347 1348 .. versionadded:: 3.2 1349 1350.. envvar:: PY_BUILTIN_MODULE_CFLAGS 1351 1352 Compiler flags to build a standard library extension module as a built-in 1353 module, like the :mod:`posix` module. 1354 1355 Default: ``$(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE_BUILTIN``. 1356 1357 .. versionadded:: 3.8 1358 1359.. envvar:: PURIFY 1360 1361 Purify command. Purify is a memory debugger program. 1362 1363 Default: empty string (not used). 1364 1365 1366Linker flags 1367------------ 1368 1369.. envvar:: LINKCC 1370 1371 Linker command used to build programs like ``python`` and ``_testembed``. 1372 1373 Default: ``$(PURIFY) $(CC)``. 1374 1375.. envvar:: CONFIGURE_LDFLAGS 1376 1377 Value of :envvar:`LDFLAGS` variable passed to the ``./configure`` script. 1378 1379 Avoid assigning :envvar:`CFLAGS`, :envvar:`LDFLAGS`, etc. so users can use 1380 them on the command line to append to these values without stomping the 1381 pre-set values. 1382 1383 .. versionadded:: 3.2 1384 1385.. envvar:: LDFLAGS_NODIST 1386 1387 :envvar:`LDFLAGS_NODIST` is used in the same manner as 1388 :envvar:`CFLAGS_NODIST`. Use it when a linker flag should *not* be part of 1389 :envvar:`LDFLAGS` once Python is installed (:gh:`65320`). 1390 1391 In particular, :envvar:`LDFLAGS` should not contain: 1392 1393 * the compiler flag ``-L`` (for setting the search path for libraries). 1394 The ``-L`` flags are processed from left to right, and any flags in 1395 :envvar:`LDFLAGS` would take precedence over user- and package-supplied ``-L`` 1396 flags. 1397 1398.. envvar:: CONFIGURE_LDFLAGS_NODIST 1399 1400 Value of :envvar:`LDFLAGS_NODIST` variable passed to the ``./configure`` 1401 script. 1402 1403 .. versionadded:: 3.8 1404 1405.. envvar:: LDFLAGS 1406 1407 Linker flags, e.g. :samp:`-L{lib_dir}` if you have libraries in a nonstandard 1408 directory *lib_dir*. 1409 1410 Both :envvar:`CPPFLAGS` and :envvar:`LDFLAGS` need to contain the shell's 1411 value to be able to build extension modules using the 1412 directories specified in the environment variables. 1413 1414.. envvar:: LIBS 1415 1416 Linker flags to pass libraries to the linker when linking the Python 1417 executable. 1418 1419 Example: ``-lrt``. 1420 1421.. envvar:: LDSHARED 1422 1423 Command to build a shared library. 1424 1425 Default: ``@LDSHARED@ $(PY_LDFLAGS)``. 1426 1427.. envvar:: BLDSHARED 1428 1429 Command to build ``libpython`` shared library. 1430 1431 Default: ``@BLDSHARED@ $(PY_CORE_LDFLAGS)``. 1432 1433.. envvar:: PY_LDFLAGS 1434 1435 Default: ``$(CONFIGURE_LDFLAGS) $(LDFLAGS)``. 1436 1437.. envvar:: PY_LDFLAGS_NODIST 1438 1439 Default: ``$(CONFIGURE_LDFLAGS_NODIST) $(LDFLAGS_NODIST)``. 1440 1441 .. versionadded:: 3.8 1442 1443.. envvar:: PY_CORE_LDFLAGS 1444 1445 Linker flags used for building the interpreter object files. 1446 1447 .. versionadded:: 3.8 1448 1449 1450.. rubric:: Footnotes 1451 1452.. [#] ``git clean -fdx`` is an even more extreme way to "clean" your 1453 checkout. It removes all files not known to Git. 1454 When bug hunting using ``git bisect``, this is 1455 `recommended between probes <https://github.com/python/cpython/issues/114505#issuecomment-1907021718>`_ 1456 to guarantee a completely clean build. **Use with care**, as it 1457 will delete all files not checked into Git, including your 1458 new, uncommitted work. 1459