1This is Python version 3.11.4 2============================= 3 4.. image:: https://github.com/python/cpython/workflows/Tests/badge.svg 5 :alt: CPython build status on GitHub Actions 6 :target: https://github.com/python/cpython/actions 7 8.. image:: https://dev.azure.com/python/cpython/_apis/build/status/Azure%20Pipelines%20CI?branchName=main 9 :alt: CPython build status on Azure DevOps 10 :target: https://dev.azure.com/python/cpython/_build/latest?definitionId=4&branchName=main 11 12.. image:: https://img.shields.io/badge/discourse-join_chat-brightgreen.svg 13 :alt: Python Discourse chat 14 :target: https://discuss.python.org/ 15 16 17Copyright © 2001-2023 Python Software Foundation. All rights reserved. 18 19See the end of this file for further copyright and license information. 20 21.. contents:: 22 23General Information 24------------------- 25 26- Website: https://www.python.org 27- Source code: https://github.com/python/cpython 28- Issue tracker: https://github.com/python/cpython/issues 29- Documentation: https://docs.python.org 30- Developer's Guide: https://devguide.python.org/ 31 32Contributing to CPython 33----------------------- 34 35For more complete instructions on contributing to CPython development, 36see the `Developer Guide`_. 37 38.. _Developer Guide: https://devguide.python.org/ 39 40Using Python 41------------ 42 43Installable Python kits, and information about using Python, are available at 44`python.org`_. 45 46.. _python.org: https://www.python.org/ 47 48Build Instructions 49------------------ 50 51On Unix, Linux, BSD, macOS, and Cygwin:: 52 53 ./configure 54 make 55 make test 56 sudo make install 57 58This will install Python as ``python3``. 59 60You can pass many options to the configure script; run ``./configure --help`` 61to find out more. On macOS case-insensitive file systems and on Cygwin, 62the executable is called ``python.exe``; elsewhere it's just ``python``. 63 64Building a complete Python installation requires the use of various 65additional third-party libraries, depending on your build platform and 66configure options. Not all standard library modules are buildable or 67useable on all platforms. Refer to the 68`Install dependencies <https://devguide.python.org/getting-started/setup-building.html#build-dependencies>`_ 69section of the `Developer Guide`_ for current detailed information on 70dependencies for various Linux distributions and macOS. 71 72On macOS, there are additional configure and build options related 73to macOS framework and universal builds. Refer to `Mac/README.rst 74<https://github.com/python/cpython/blob/main/Mac/README.rst>`_. 75 76On Windows, see `PCbuild/readme.txt 77<https://github.com/python/cpython/blob/main/PCbuild/readme.txt>`_. 78 79If you wish, you can create a subdirectory and invoke configure from there. 80For example:: 81 82 mkdir debug 83 cd debug 84 ../configure --with-pydebug 85 make 86 make test 87 88(This will fail if you *also* built at the top-level directory. You should do 89a ``make clean`` at the top-level first.) 90 91To get an optimized build of Python, ``configure --enable-optimizations`` 92before you run ``make``. This sets the default make targets up to enable 93Profile Guided Optimization (PGO) and may be used to auto-enable Link Time 94Optimization (LTO) on some platforms. For more details, see the sections 95below. 96 97Profile Guided Optimization 98^^^^^^^^^^^^^^^^^^^^^^^^^^^ 99 100PGO takes advantage of recent versions of the GCC or Clang compilers. If used, 101either via ``configure --enable-optimizations`` or by manually running 102``make profile-opt`` regardless of configure flags, the optimized build 103process will perform the following steps: 104 105The entire Python directory is cleaned of temporary files that may have 106resulted from a previous compilation. 107 108An instrumented version of the interpreter is built, using suitable compiler 109flags for each flavor. Note that this is just an intermediary step. The 110binary resulting from this step is not good for real-life workloads as it has 111profiling instructions embedded inside. 112 113After the instrumented interpreter is built, the Makefile will run a training 114workload. This is necessary in order to profile the interpreter's execution. 115Note also that any output, both stdout and stderr, that may appear at this step 116is suppressed. 117 118The final step is to build the actual interpreter, using the information 119collected from the instrumented one. The end result will be a Python binary 120that is optimized; suitable for distribution or production installation. 121 122 123Link Time Optimization 124^^^^^^^^^^^^^^^^^^^^^^ 125 126Enabled via configure's ``--with-lto`` flag. LTO takes advantage of the 127ability of recent compiler toolchains to optimize across the otherwise 128arbitrary ``.o`` file boundary when building final executables or shared 129libraries for additional performance gains. 130 131 132What's New 133---------- 134 135We have a comprehensive overview of the changes in the `What's New in Python 1363.11 <https://docs.python.org/3.11/whatsnew/3.11.html>`_ document. For a more 137detailed change log, read `Misc/NEWS 138<https://github.com/python/cpython/tree/main/Misc/NEWS.d>`_, but a full 139accounting of changes can only be gleaned from the `commit history 140<https://github.com/python/cpython/commits/main>`_. 141 142If you want to install multiple versions of Python, see the section below 143entitled "Installing multiple versions". 144 145 146Documentation 147------------- 148 149`Documentation for Python 3.11 <https://docs.python.org/3.11/>`_ is online, 150updated daily. 151 152It can also be downloaded in many formats for faster access. The documentation 153is downloadable in HTML, PDF, and reStructuredText formats; the latter version 154is primarily for documentation authors, translators, and people with special 155formatting requirements. 156 157For information about building Python's documentation, refer to `Doc/README.rst 158<https://github.com/python/cpython/blob/main/Doc/README.rst>`_. 159 160 161Converting From Python 2.x to 3.x 162--------------------------------- 163 164Significant backward incompatible changes were made for the release of Python 1653.0, which may cause programs written for Python 2 to fail when run with Python 1663. For more information about porting your code from Python 2 to Python 3, see 167the `Porting HOWTO <https://docs.python.org/3/howto/pyporting.html>`_. 168 169 170Testing 171------- 172 173To test the interpreter, type ``make test`` in the top-level directory. The 174test set produces some output. You can generally ignore the messages about 175skipped tests due to optional features which can't be imported. If a message 176is printed about a failed test or a traceback or core dump is produced, 177something is wrong. 178 179By default, tests are prevented from overusing resources like disk space and 180memory. To enable these tests, run ``make testall``. 181 182If any tests fail, you can re-run the failing test(s) in verbose mode. For 183example, if ``test_os`` and ``test_gdb`` failed, you can run:: 184 185 make test TESTOPTS="-v test_os test_gdb" 186 187If the failure persists and appears to be a problem with Python rather than 188your environment, you can `file a bug report 189<https://github.com/python/cpython/issues>`_ and include relevant output from 190that command to show the issue. 191 192See `Running & Writing Tests <https://devguide.python.org/testing/run-write-tests.html>`_ 193for more on running tests. 194 195Installing multiple versions 196---------------------------- 197 198On Unix and Mac systems if you intend to install multiple versions of Python 199using the same installation prefix (``--prefix`` argument to the configure 200script) you must take care that your primary python executable is not 201overwritten by the installation of a different version. All files and 202directories installed using ``make altinstall`` contain the major and minor 203version and can thus live side-by-side. ``make install`` also creates 204``${prefix}/bin/python3`` which refers to ``${prefix}/bin/python3.X``. If you 205intend to install multiple versions using the same prefix you must decide which 206version (if any) is your "primary" version. Install that version using ``make 207install``. Install all other versions using ``make altinstall``. 208 209For example, if you want to install Python 2.7, 3.6, and 3.11 with 3.11 being the 210primary version, you would execute ``make install`` in your 3.11 build directory 211and ``make altinstall`` in the others. 212 213 214Issue Tracker and Mailing List 215------------------------------ 216 217Bug reports are welcome! You can use Github to `report bugs 218<https://github.com/python/cpython/issues>`_, and/or `submit pull requests 219<https://github.com/python/cpython/pulls>`_. 220 221You can also follow development discussion on the `python-dev mailing list 222<https://mail.python.org/mailman/listinfo/python-dev/>`_. 223 224 225Proposals for enhancement 226------------------------- 227 228If you have a proposal to change Python, you may want to send an email to the 229`comp.lang.python`_ or `python-ideas`_ mailing lists for initial feedback. A 230Python Enhancement Proposal (PEP) may be submitted if your idea gains ground. 231All current PEPs, as well as guidelines for submitting a new PEP, are listed at 232`peps.python.org <https://peps.python.org/>`_. 233 234.. _python-ideas: https://mail.python.org/mailman/listinfo/python-ideas/ 235.. _comp.lang.python: https://mail.python.org/mailman/listinfo/python-list 236 237 238Release Schedule 239---------------- 240 241See :pep:`664` for Python 3.11 release details. 242 243 244Copyright and License Information 245--------------------------------- 246 247 248Copyright © 2001-2023 Python Software Foundation. All rights reserved. 249 250Copyright © 2000 BeOpen.com. All rights reserved. 251 252Copyright © 1995-2001 Corporation for National Research Initiatives. All 253rights reserved. 254 255Copyright © 1991-1995 Stichting Mathematisch Centrum. All rights reserved. 256 257See the `LICENSE <https://github.com/python/cpython/blob/main/LICENSE>`_ for 258information on the history of this software, terms & conditions for usage, and a 259DISCLAIMER OF ALL WARRANTIES. 260 261This Python distribution contains *no* GNU General Public License (GPL) code, 262so it may be used in proprietary projects. There are interfaces to some GNU 263code but these are entirely optional. 264 265All trademarks referenced herein are property of their respective holders. 266
