CINXE.COM

<!doctype html> <html class="no-js" lang="en" data-content_root="../../"> <head><meta charset="utf-8"/> <meta name="viewport" content="width=device-width,initial-scale=1"/> <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" /> <meta property="og:title" content="Setup and building" /> <meta property="og:type" content="website" /> <meta property="og:url" content="https://devguide.python.org/getting-started/setup-building/" /> <meta property="og:site_name" content="Python Developer's Guide" /> <meta property="og:description" content="These instructions cover how to get a working copy of the source code and a compiled version of the CPython interpreter (CPython is the version of Python available from https://www.python.org/). It..." /> <meta property="og:image" content="https://devguide.python.org/_static/og-image-200x200.png" /> <meta property="og:image:alt" content="Python Developer's Guide" /> <meta name="description" content="These instructions cover how to get a working copy of the source code and a compiled version of the CPython interpreter (CPython is the version of Python available from https://www.python.org/). It..." /> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="theme-color" content="#3776ab"> <link rel="index" title="Index" href="../../genindex/" /><link rel="search" title="Search" href="../../search/" /><link rel="next" title="Fixing “easy” issues (and beyond)" href="../fixing-issues/" /><link rel="prev" title="Getting started" href="../" /> <link rel="shortcut icon" href="../../_static/favicon.png"/> <title>Setup and building</title> <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=8f2a1f02" /> <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?v=354aac6f" /> <link rel="stylesheet" type="text/css" href="../../_static/copybutton.css?v=76b2166b" /> <link rel="stylesheet" type="text/css" href="../../_static/tabs.css?v=4c969af8" /> <link rel="stylesheet" type="text/css" href="../../_static/styles/furo-extensions.css?v=302659d7" /> <link rel="stylesheet" type="text/css" href="../../_static/devguide_overrides.css?v=ac29e0ef" /> <style> body { --color-code-background: #f8f8f8; --color-code-foreground: black; } @media not print { body[data-theme="dark"] { --color-code-background: #202020; --color-code-foreground: #d0d0d0; } @media (prefers-color-scheme: dark) { body:not([data-theme="light"]) { --color-code-background: #202020; --color-code-foreground: #d0d0d0; } } } </style><script async type="text/javascript" src="/_/static/javascript/readthedocs-addons.js"></script><meta name="readthedocs-project-slug" content="cpython-devguide" /><meta name="readthedocs-version-slug" content="latest" /><meta name="readthedocs-resolver-filename" content="/getting-started/setup-building/" /><meta name="readthedocs-http-status" content="200" /></head> <body> <script> document.body.dataset.theme = localStorage.getItem("theme") || "auto"; </script> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-toc" viewBox="0 0 24 24"> <title>Contents</title> <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024"> <path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/> </svg> </symbol> <symbol id="svg-menu" viewBox="0 0 24 24"> <title>Menu</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu"> <line x1="3" y1="12" x2="21" y2="12"></line> <line x1="3" y1="6" x2="21" y2="6"></line> <line x1="3" y1="18" x2="21" y2="18"></line> </svg> </symbol> <symbol id="svg-arrow-right" viewBox="0 0 24 24"> <title>Expand</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right"> <polyline points="9 18 15 12 9 6"></polyline> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24"> <title>Light mode</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="feather-sun"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24"> <title>Dark mode</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon"> <path stroke="none" d="M0 0h24v24H0z" fill="none" /> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" /> </svg> </symbol> <symbol id="svg-sun-with-moon" viewBox="0 0 24 24"> <title>Auto light/dark, in light mode</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-custom-derived-from-feather-sun-and-tabler-moon"> <path style="opacity: 50%" d="M 5.411 14.504 C 5.471 14.504 5.532 14.504 5.591 14.504 C 3.639 16.319 4.383 19.569 6.931 20.352 C 7.693 20.586 8.512 20.551 9.25 20.252 C 8.023 23.207 4.056 23.725 2.11 21.184 C 0.166 18.642 1.702 14.949 4.874 14.536 C 5.051 14.512 5.231 14.5 5.411 14.5 L 5.411 14.504 Z"/> <line x1="14.5" y1="3.25" x2="14.5" y2="1.25"/> <line x1="14.5" y1="15.85" x2="14.5" y2="17.85"/> <line x1="10.044" y1="5.094" x2="8.63" y2="3.68"/> <line x1="19" y1="14.05" x2="20.414" y2="15.464"/> <line x1="8.2" y1="9.55" x2="6.2" y2="9.55"/> <line x1="20.8" y1="9.55" x2="22.8" y2="9.55"/> <line x1="10.044" y1="14.006" x2="8.63" y2="15.42"/> <line x1="19" y1="5.05" x2="20.414" y2="3.636"/> <circle cx="14.5" cy="9.55" r="3.6"/> </svg> </symbol> <symbol id="svg-moon-with-sun" viewBox="0 0 24 24"> <title>Auto light/dark, in dark mode</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-custom-derived-from-feather-sun-and-tabler-moon"> <path d="M 8.282 7.007 C 8.385 7.007 8.494 7.007 8.595 7.007 C 5.18 10.184 6.481 15.869 10.942 17.24 C 12.275 17.648 13.706 17.589 15 17.066 C 12.851 22.236 5.91 23.143 2.505 18.696 C -0.897 14.249 1.791 7.786 7.342 7.063 C 7.652 7.021 7.965 7 8.282 7 L 8.282 7.007 Z"/> <line style="opacity: 50%" x1="18" y1="3.705" x2="18" y2="2.5"/> <line style="opacity: 50%" x1="18" y1="11.295" x2="18" y2="12.5"/> <line style="opacity: 50%" x1="15.316" y1="4.816" x2="14.464" y2="3.964"/> <line style="opacity: 50%" x1="20.711" y1="10.212" x2="21.563" y2="11.063"/> <line style="opacity: 50%" x1="14.205" y1="7.5" x2="13.001" y2="7.5"/> <line style="opacity: 50%" x1="21.795" y1="7.5" x2="23" y2="7.5"/> <line style="opacity: 50%" x1="15.316" y1="10.184" x2="14.464" y2="11.036"/> <line style="opacity: 50%" x1="20.711" y1="4.789" x2="21.563" y2="3.937"/> <circle style="opacity: 50%" cx="18" cy="7.5" r="2.169"/> </svg> </symbol> <symbol id="svg-pencil" viewBox="0 0 24 24"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-pencil-code"> <path d="M4 20h4l10.5 -10.5a2.828 2.828 0 1 0 -4 -4l-10.5 10.5v4" /> <path d="M13.5 6.5l4 4" /> <path d="M20 21l2 -2l-2 -2" /> <path d="M17 17l-2 2l2 2" /> </svg> </symbol> <symbol id="svg-eye" viewBox="0 0 24 24"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-eye-code"> <path stroke="none" d="M0 0h24v24H0z" fill="none" /> <path d="M10 12a2 2 0 1 0 4 0a2 2 0 0 0 -4 0" /> <path d="M11.11 17.958c-3.209 -.307 -5.91 -2.293 -8.11 -5.958c2.4 -4 5.4 -6 9 -6c3.6 0 6.6 2 9 6c-.21 .352 -.427 .688 -.647 1.008" /> <path d="M20 21l2 -2l-2 -2" /> <path d="M17 17l-2 2l2 2" /> </svg> </symbol> </svg> <input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation"> <input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc"> <label class="overlay sidebar-overlay" for="__navigation"> <div class="visually-hidden">Hide navigation sidebar</div> </label> <label class="overlay toc-overlay" for="__toc"> <div class="visually-hidden">Hide table of contents sidebar</div> </label> <a class="skip-to-content muted-link" href="#furo-main-content">Skip to content</a> <div class="page"> <header class="mobile-header"> <div class="header-left"> <label class="nav-overlay-icon" for="__navigation"> <div class="visually-hidden">Toggle site navigation sidebar</div> <i class="icon"><svg><use href="#svg-menu"></use></svg></i> </label> </div> <div class="header-center"> <a href="../../"><div class="brand">Python Developer's Guide</div></a> </div> <div class="header-right"> <div class="theme-toggle-container theme-toggle-header"> <button class="theme-toggle"> <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div> <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg> <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg> <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg> </button> </div> <label class="toc-overlay-icon toc-header-icon" for="__toc"> <div class="visually-hidden">Toggle table of contents sidebar</div> <i class="icon"><svg><use href="#svg-toc"></use></svg></i> </label> </div> </header> <aside class="sidebar-drawer"> <div class="sidebar-container"> <div class="sidebar-sticky"><a class="sidebar-brand" href="../../"> <div class="sidebar-logo-container"> <img class="sidebar-logo" src="../../_static/python-logo.svg" alt="Logo"/> </div> <span class="sidebar-brand-text">Python Developer's Guide</span> </a><form class="sidebar-search-container" method="get" action="../../search/" role="search"> <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search"> <input type="hidden" name="check_keywords" value="yes"> <input type="hidden" name="area" value="default"> </form> <div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree"> <ul class="current"> <li class="toctree-l1 current has-children"><a class="reference internal" href="../">Getting started</a><input checked="" class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" role="switch" type="checkbox"/><label for="toctree-checkbox-1"><div class="visually-hidden">Toggle navigation of Getting started</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul class="current"> <li class="toctree-l2 current current-page"><a class="current reference internal" href="#">Setup and building</a></li> <li class="toctree-l2"><a class="reference internal" href="../fixing-issues/">Fixing “easy” issues (and beyond)</a></li> <li class="toctree-l2"><a class="reference internal" href="../git-boot-camp/">Git bootcamp and cheat sheet</a></li> <li class="toctree-l2"><a class="reference internal" href="../pull-request-lifecycle/">Lifecycle of a pull request</a></li> <li class="toctree-l2"><a class="reference internal" href="../getting-help/">Where to get help</a></li> <li class="toctree-l2"><a class="reference internal" href="../generative-ai/">Generative AI</a></li> </ul> </li> <li class="toctree-l1 has-children"><a class="reference internal" href="../../developer-workflow/">Development workflow</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" role="switch" type="checkbox"/><label for="toctree-checkbox-2"><div class="visually-hidden">Toggle navigation of Development workflow</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../../developer-workflow/communication-channels/">Following Python’s development</a></li> <li class="toctree-l2"><a class="reference internal" href="../../developer-workflow/development-cycle/">Development cycle</a></li> <li class="toctree-l2"><a class="reference internal" href="../../developer-workflow/stdlib/">Adding to the stdlib</a></li> <li class="toctree-l2"><a class="reference internal" href="../../developer-workflow/extension-modules/">Standard library extension modules</a></li> <li class="toctree-l2"><a class="reference internal" href="../../developer-workflow/c-api/">Changing Python’s C API</a></li> <li class="toctree-l2"><a class="reference internal" href="../../developer-workflow/lang-changes/">Changing the Python language</a></li> <li class="toctree-l2"><a class="reference internal" href="../../developer-workflow/grammar/">Changing CPython’s grammar</a></li> <li class="toctree-l2"><a class="reference internal" href="../../developer-workflow/porting/">Porting to a new platform</a></li> <li class="toctree-l2"><a class="reference internal" href="../../developer-workflow/sbom/">Software Bill-of-Materials (SBOM)</a></li> <li class="toctree-l2"><a class="reference internal" href="../../developer-workflow/psrt/">Python Security Response Team (PSRT)</a></li> </ul> </li> <li class="toctree-l1 has-children"><a class="reference internal" href="../../triage/">Issues and triaging</a><input class="toctree-checkbox" id="toctree-checkbox-3" name="toctree-checkbox-3" role="switch" type="checkbox"/><label for="toctree-checkbox-3"><div class="visually-hidden">Toggle navigation of Issues and triaging</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../../triage/issue-tracker/">Issue tracker</a></li> <li class="toctree-l2"><a class="reference internal" href="../../triage/triaging/">Triaging an issue</a></li> <li class="toctree-l2"><a class="reference internal" href="../../triage/labels/">GitHub labels</a></li> <li class="toctree-l2"><a class="reference internal" href="../../triage/github-bpo-faq/">GitHub issues for BPO users</a></li> <li class="toctree-l2"><a class="reference internal" href="../../triage/triage-team/">Triage Team</a></li> </ul> </li> <li class="toctree-l1 has-children"><a class="reference internal" href="../../documentation/">Documentation</a><input class="toctree-checkbox" id="toctree-checkbox-4" name="toctree-checkbox-4" role="switch" type="checkbox"/><label for="toctree-checkbox-4"><div class="visually-hidden">Toggle navigation of Documentation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../../documentation/start-documenting/">Getting started</a></li> <li class="toctree-l2"><a class="reference internal" href="../../documentation/help-documenting/">Helping with documentation</a></li> <li class="toctree-l2"><a class="reference internal" href="../../documentation/style-guide/">Style guide</a></li> <li class="toctree-l2"><a class="reference internal" href="../../documentation/markup/">reStructuredText markup</a></li> <li class="toctree-l2"><a class="reference internal" href="../../documentation/translating/">Translating</a></li> <li class="toctree-l2"><a class="reference internal" href="../../documentation/devguide/">Helping with the Developer’s Guide</a></li> </ul> </li> <li class="toctree-l1 has-children"><a class="reference internal" href="../../testing/">Testing and buildbots</a><input class="toctree-checkbox" id="toctree-checkbox-5" name="toctree-checkbox-5" role="switch" type="checkbox"/><label for="toctree-checkbox-5"><div class="visually-hidden">Toggle navigation of Testing and buildbots</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../../testing/run-write-tests/">Running and writing tests</a></li> <li class="toctree-l2"><a class="reference internal" href="../../testing/silence-warnings/">Silence warnings from the test suite</a></li> <li class="toctree-l2"><a class="reference internal" href="../../testing/coverage/">Increase test coverage</a></li> <li class="toctree-l2"><a class="reference internal" href="../../testing/buildbots/">Working with buildbots</a></li> <li class="toctree-l2"><a class="reference internal" href="../../testing/new-buildbot-worker/">New buildbot workers</a></li> </ul> </li> <li class="toctree-l1 has-children"><a class="reference internal" href="../../development-tools/">Development tools</a><input class="toctree-checkbox" id="toctree-checkbox-6" name="toctree-checkbox-6" role="switch" type="checkbox"/><label for="toctree-checkbox-6"><div class="visually-hidden">Toggle navigation of Development tools</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../../development-tools/clinic/">Argument Clinic</a></li> <li class="toctree-l2"><a class="reference internal" href="../../development-tools/gdb/">GDB support</a></li> <li class="toctree-l2"><a class="reference internal" href="../../development-tools/clang/">Dynamic analysis with Clang</a></li> <li class="toctree-l2"><a class="reference internal" href="../../development-tools/warnings/">Tools for tracking compiler warnings</a></li> </ul> </li> <li class="toctree-l1 has-children"><a class="reference internal" href="../../core-developers/">Core developers</a><input class="toctree-checkbox" id="toctree-checkbox-7" name="toctree-checkbox-7" role="switch" type="checkbox"/><label for="toctree-checkbox-7"><div class="visually-hidden">Toggle navigation of Core developers</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../../core-developers/responsibilities/">Responsibilities</a></li> <li class="toctree-l2"><a class="reference internal" href="../../core-developers/committing/">Accepting pull requests</a></li> <li class="toctree-l2"><a class="reference internal" href="../../core-developers/experts/">Experts index</a></li> <li class="toctree-l2"><a class="reference internal" href="../../core-developers/developer-log/">Developer log</a></li> <li class="toctree-l2"><a class="reference internal" href="../../core-developers/motivations/">Motivations and affiliations</a></li> <li class="toctree-l2"><a class="reference internal" href="../../core-developers/become-core-developer/">How to become a core developer</a></li> <li class="toctree-l2"><a class="reference internal" href="../../core-developers/memorialization/">Memorialization</a></li> </ul> </li> <li class="toctree-l1 has-children"><a class="reference internal" href="../../internals/">CPython’s internals</a><input class="toctree-checkbox" id="toctree-checkbox-8" name="toctree-checkbox-8" role="switch" type="checkbox"/><label for="toctree-checkbox-8"><div class="visually-hidden">Toggle navigation of CPython’s internals</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../../internals/exploring/">CPython source code</a></li> <li class="toctree-l2"><a class="reference internal" href="../../internals/parser/">Guide to the parser</a></li> <li class="toctree-l2"><a class="reference internal" href="../../internals/compiler/">Compiler design</a></li> <li class="toctree-l2"><a class="reference internal" href="../../internals/interpreter/">The bytecode interpreter</a></li> <li class="toctree-l2"><a class="reference internal" href="../../internals/garbage-collector/">Garbage collector design</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="../../versions/">Status of Python versions</a></li> <li class="toctree-l1 has-children"><a class="reference internal" href="../../contrib/">Python Contributor’s Guide (draft)</a><input class="toctree-checkbox" id="toctree-checkbox-9" name="toctree-checkbox-9" role="switch" type="checkbox"/><label for="toctree-checkbox-9"><div class="visually-hidden">Toggle navigation of Python Contributor’s Guide (draft)</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../../contrib/contrib-plan/">[Plan for the Contributor’s Guide]</a></li> <li class="toctree-l2"><a class="reference internal" href="../../contrib/intro/">Introduction</a></li> <li class="toctree-l2 has-children"><a class="reference internal" href="../../contrib/project/">The CPython project</a><input class="toctree-checkbox" id="toctree-checkbox-10" name="toctree-checkbox-10" role="switch" type="checkbox"/><label for="toctree-checkbox-10"><div class="visually-hidden">Toggle navigation of The CPython project</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../../contrib/project/conduct/">Code of Conduct</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/project/roles/">Roles</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/project/governance/">Governance</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/project/generative-ai/">Generative AI</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/project/github/">GitHub</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/project/directory-structure/">Directory structure</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/project/channels/">Communication channels</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/project/outreach/">Outreach</a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../../contrib/triage/">Issues and triaging</a><input class="toctree-checkbox" id="toctree-checkbox-11" name="toctree-checkbox-11" role="switch" type="checkbox"/><label for="toctree-checkbox-11"><div class="visually-hidden">Toggle navigation of Issues and triaging</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../../contrib/triage/issue-tracker/">Issue tracker</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/triage/triaging/">Triaging an issue</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/triage/labels/">GitHub labels</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/triage/reviewing/">Reviewing</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/triage/triage-team/">Triage Team</a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../../contrib/doc/">Documentation contributions</a><input class="toctree-checkbox" id="toctree-checkbox-12" name="toctree-checkbox-12" role="switch" type="checkbox"/><label for="toctree-checkbox-12"><div class="visually-hidden">Toggle navigation of Documentation contributions</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../../contrib/doc/start-documenting/">Getting started</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/doc/help-documenting/">Helping with documentation</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/doc/style-guide/">Style guide</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/doc/markup/">reStructuredText markup</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/doc/pull-request-lifecycle/">Pull request lifecycle</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/doc/translating/">Translating</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/doc/devguide/">Helping with the Developer’s Guide</a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../../contrib/code/">Code contributions</a><input class="toctree-checkbox" id="toctree-checkbox-13" name="toctree-checkbox-13" role="switch" type="checkbox"/><label for="toctree-checkbox-13"><div class="visually-hidden">Toggle navigation of Code contributions</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../../contrib/code/setup/">Setup and building</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/code/git/">Git tips</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/code/pull-request-lifecycle/">Pull request lifecycle</a></li> <li class="toctree-l3 has-children"><a class="reference internal" href="../../contrib/code/developer-workflow/">Development workflow</a><input class="toctree-checkbox" id="toctree-checkbox-14" name="toctree-checkbox-14" role="switch" type="checkbox"/><label for="toctree-checkbox-14"><div class="visually-hidden">Toggle navigation of Development workflow</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l4"><a class="reference internal" href="../../developer-workflow/communication-channels/">Following Python’s development</a></li> <li class="toctree-l4"><a class="reference internal" href="../../developer-workflow/development-cycle/">Development cycle</a></li> <li class="toctree-l4"><a class="reference internal" href="../../developer-workflow/stdlib/">Adding to the stdlib</a></li> <li class="toctree-l4"><a class="reference internal" href="../../developer-workflow/extension-modules/">Standard library extension modules</a></li> <li class="toctree-l4"><a class="reference internal" href="../../developer-workflow/c-api/">Changing Python’s C API</a></li> <li class="toctree-l4"><a class="reference internal" href="../../developer-workflow/lang-changes/">Changing the Python language</a></li> <li class="toctree-l4"><a class="reference internal" href="../../developer-workflow/grammar/">Changing CPython’s grammar</a></li> <li class="toctree-l4"><a class="reference internal" href="../../developer-workflow/porting/">Porting to a new platform</a></li> <li class="toctree-l4"><a class="reference internal" href="../../developer-workflow/sbom/">Software Bill-of-Materials (SBOM)</a></li> <li class="toctree-l4"><a class="reference internal" href="../../developer-workflow/psrt/">Python Security Response Team (PSRT)</a></li> </ul> </li> <li class="toctree-l3 has-children"><a class="reference internal" href="../../contrib/code/testing/">Testing and buildbots</a><input class="toctree-checkbox" id="toctree-checkbox-15" name="toctree-checkbox-15" role="switch" type="checkbox"/><label for="toctree-checkbox-15"><div class="visually-hidden">Toggle navigation of Testing and buildbots</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l4"><a class="reference internal" href="../../testing/run-write-tests/">Running and writing tests</a></li> <li class="toctree-l4"><a class="reference internal" href="../../testing/silence-warnings/">Silence warnings from the test suite</a></li> <li class="toctree-l4"><a class="reference internal" href="../../testing/coverage/">Increase test coverage</a></li> <li class="toctree-l4"><a class="reference internal" href="../../testing/buildbots/">Working with buildbots</a></li> <li class="toctree-l4"><a class="reference internal" href="../../testing/new-buildbot-worker/">New buildbot workers</a></li> </ul> </li> <li class="toctree-l3 has-children"><a class="reference internal" href="../../contrib/code/development-tools/">Development tools</a><input class="toctree-checkbox" id="toctree-checkbox-16" name="toctree-checkbox-16" role="switch" type="checkbox"/><label for="toctree-checkbox-16"><div class="visually-hidden">Toggle navigation of Development tools</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l4"><a class="reference internal" href="../../development-tools/clinic/">Argument Clinic</a></li> <li class="toctree-l4"><a class="reference internal" href="../../development-tools/gdb/">GDB support</a></li> <li class="toctree-l4"><a class="reference internal" href="../../development-tools/clang/">Dynamic analysis with Clang</a></li> <li class="toctree-l4"><a class="reference internal" href="../../development-tools/warnings/">Tools for tracking compiler warnings</a></li> </ul> </li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../../contrib/core-team/">Core team</a><input class="toctree-checkbox" id="toctree-checkbox-17" name="toctree-checkbox-17" role="switch" type="checkbox"/><label for="toctree-checkbox-17"><div class="visually-hidden">Toggle navigation of Core team</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../../contrib/core-team/responsibilities/">Responsibilities</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/core-team/committing/">Accepting pull requests</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/core-team/experts/">Experts index</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/core-team/developer-log/">Developer log</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/core-team/motivations/">Motivations and affiliations</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/core-team/join-team/">How to join the core team</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="../../contrib/user-success/">Accessibility, design, and user success</a></li> <li class="toctree-l2"><a class="reference internal" href="../../contrib/security/">Security and infrastructure contributions</a></li> <li class="toctree-l2 has-children"><a class="reference internal" href="../../contrib/workflows/">Workflows</a><input class="toctree-checkbox" id="toctree-checkbox-18" name="toctree-checkbox-18" role="switch" type="checkbox"/><label for="toctree-checkbox-18"><div class="visually-hidden">Toggle navigation of Workflows</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../../contrib/workflows/install-git/">Install Git</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/workflows/get-source/">Get the source code</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/workflows/install-dependencies/">Install Dependencies</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/workflows/compile/">Compile and build</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/workflows/regenerate/">Regenerating auto-created files</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/workflows/troubleshooting/">Install Git</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/workflows/codespaces/">Using GitHub Codespaces</a></li> </ul> </li> </ul> </li> </ul> </div> </div> </div> </div> </aside> <div class="main"> <div class="content"> <div class="article-container"> <a href="#" class="back-to-top muted-link"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"> <path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path> </svg> <span>Back to top</span> </a> <div class="content-icon-container"> <div class="view-this-page"> <a class="muted-link" href="https://github.com/python/devguide/blob/main/getting-started/setup-building.rst?plain=true" title="View this page"> <svg><use href="#svg-eye"></use></svg> <span class="visually-hidden">View this page</span> </a> </div><div class="edit-this-page"> <a class="muted-link" href="https://github.com/python/devguide/edit/main/getting-started/setup-building.rst" title="Edit this page"> <svg><use href="#svg-pencil"></use></svg> <span class="visually-hidden">Edit this page</span> </a> </div><div class="theme-toggle-container theme-toggle-content"> <button class="theme-toggle"> <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div> <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg> <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg> <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg> </button> </div> <label class="toc-overlay-icon toc-content-icon" for="__toc"> <div class="visually-hidden">Toggle table of contents sidebar</div> <i class="icon"><svg><use href="#svg-toc"></use></svg></i> </label> </div> <article role="main" id="furo-main-content"> <section id="setup-and-building"> <span id="setup"></span><span id="setup-building"></span><h1>Setup and building<a class="headerlink" href="#setup-and-building" title="Link to this heading">¶</a></h1> <script> document.addEventListener('DOMContentLoaded', function() { activateTab(getOS()); }); </script><p>These instructions cover how to get a working copy of the source code and a compiled version of the CPython interpreter (CPython is the version of Python available from <a class="reference external" href="https://www.python.org/">https://www.python.org/</a>). It also gives an overview of the directory structure of the CPython source code.</p> <p>Alternatively, if you have <a class="reference external" href="https://www.docker.com/">Docker</a> installed you might want to use <a class="reference external" href="https://gitlab.com/python-devs/ci-images/blob/main/README.md">our official images</a>. These contain the latest releases of several Python versions, along with Git head, and are provided for development and testing purposes only.</p> <div class="admonition seealso"> <p class="admonition-title">See also</p> <p>The <a class="reference internal" href="../../#quick-reference"><span class="std std-ref">Quick reference</span></a> gives brief summary of the process from installing Git to submitting a pull request.</p> </div> <section id="install-git"> <span id="vcsetup"></span><h2>Install Git<a class="headerlink" href="#install-git" title="Link to this heading">¶</a></h2> <p>CPython is developed using <a class="reference external" href="https://git-scm.com">Git</a> for version control. The Git command line program is named <code class="docutils literal notranslate"><span class="pre">git</span></code>; this is also used to refer to Git itself. Git is easily available for all common operating systems.</p> <ul> <li><p><strong>Install</strong></p> <p>As the CPython repo is hosted on GitHub, please refer to either the <a class="reference external" href="https://docs.github.com/en/get-started/getting-started-with-git/set-up-git">GitHub setup instructions</a> or the <a class="reference external" href="https://git-scm.com">Git project instructions</a> for step-by-step installation directions. You may also want to consider a graphical client such as <a class="reference external" href="https://tortoisegit.org/">TortoiseGit</a> or <a class="reference external" href="https://github.com/apps/desktop">GitHub Desktop</a>.</p> </li> <li><p><strong>Configure</strong></p> <p>Configure <a class="reference internal" href="../git-boot-camp/#set-up-name-email"><span class="std std-ref">your name and email</span></a> and create <a class="reference external" href="https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account">an SSH key</a> as this will allow you to interact with GitHub without typing a username and password each time you execute a command, such as <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code>, <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span></code>, or <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">fetch</span></code>. On Windows, you should also <a class="reference internal" href="../git-boot-camp/#autocrlf"><span class="std std-ref">enable autocrlf</span></a>.</p> </li> </ul> </section> <section id="get-the-source-code"> <span id="checkout"></span><h2>Get the source code<a class="headerlink" href="#get-the-source-code" title="Link to this heading">¶</a></h2> <p>The CPython repo is hosted on GitHub. To get a copy of the source code you should <a class="reference internal" href="../git-boot-camp/#fork-cpython"><span class="std std-ref">fork the Python repository on GitHub</span></a>, <a class="reference internal" href="../git-boot-camp/#clone-your-fork"><span class="std std-ref">create a local clone of your personal fork, and configure the remotes</span></a>.</p> <p>You will only need to execute these steps once per machine:</p> <ol class="arabic"> <li><p>Go to <a class="reference external" href="https://github.com/python/cpython">https://github.com/python/cpython</a>.</p></li> <li><p>Press <span class="guilabel">Fork</span> on the top right.</p></li> <li><p>When asked where to fork the repository, choose to fork it to your username.</p></li> <li><p>Your fork will be created at <code class="samp docutils literal notranslate"><span class="pre">https://github.com/</span><em><span class="pre"><username></span></em><span class="pre">/cpython</span></code>.</p></li> <li><p>Clone your GitHub fork (replace <code class="docutils literal notranslate"><span class="pre"><username></span></code> with your username):</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>git<span class="w"> </span>clone<span class="w"> </span>git@github.com:<username>/cpython.git </pre></div> </div> <p>(You can use both SSH-based or HTTPS-based URLs.)</p> </li> </ol> <ol class="arabic" start="6"> <li><p>Add an <code class="docutils literal notranslate"><span class="pre">upstream</span></code> remote, then configure <code class="docutils literal notranslate"><span class="pre">git</span></code> to pull <code class="docutils literal notranslate"><span class="pre">main</span></code> from <code class="docutils literal notranslate"><span class="pre">upstream</span></code> and always push to <code class="docutils literal notranslate"><span class="pre">origin</span></code>:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nb">cd</span><span class="w"> </span>cpython <span class="gp">$ </span>git<span class="w"> </span>remote<span class="w"> </span>add<span class="w"> </span>upstream<span class="w"> </span>https://github.com/python/cpython <span class="gp">$ </span>git<span class="w"> </span>config<span class="w"> </span>--local<span class="w"> </span>branch.main.remote<span class="w"> </span>upstream <span class="gp">$ </span>git<span class="w"> </span>remote<span class="w"> </span>set-url<span class="w"> </span>--push<span class="w"> </span>upstream<span class="w"> </span>git@github.com:<your-username>/cpython.git </pre></div> </div> </li> <li><p>Verify that your setup is correct:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>git<span class="w"> </span>remote<span class="w"> </span>-v <span class="go">origin git@github.com:<your-username>/cpython.git (fetch)</span> <span class="go">origin git@github.com:<your-username>/cpython.git (push)</span> <span class="go">upstream https://github.com/python/cpython (fetch)</span> <span class="go">upstream git@github.com:<your-username>/cpython.git (push)</span> <span class="gp">$ </span>git<span class="w"> </span>config<span class="w"> </span>branch.main.remote <span class="go">upstream</span> </pre></div> </div> </li> </ol> <p>For more information about these commands see <a class="reference internal" href="../git-boot-camp/#git-boot-camp"><span class="std std-ref">Git Bootcamp and Cheat Sheet</span></a>.</p> <p>If you did everything correctly, you should now have a copy of the code in the <code class="docutils literal notranslate"><span class="pre">cpython</span></code> directory and two remotes that refer to your own GitHub fork (<code class="docutils literal notranslate"><span class="pre">origin</span></code>) and the official CPython repository (<code class="docutils literal notranslate"><span class="pre">upstream</span></code>).</p> <p>If you want a working copy of an already-released version of Python, that is, a version in <a class="reference internal" href="../../developer-workflow/development-cycle/#maintbranch"><span class="std std-ref">maintenance mode</span></a>, you can checkout a release branch. For instance, to checkout a working copy of Python 3.13, do <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">switch</span> <span class="pre">3.13</span></code>.</p> <p>You will need to re-compile CPython when you do such an update.</p> <p>Do note that CPython will notice that it is being run from a working copy. This means that if you edit CPython’s source code in your working copy, changes to Python code will be picked up by the interpreter for immediate use and testing. (If you change C code, you will need to recompile the affected files as described below.)</p> <p>Changes for the documentation can be made from the same repository; see <a class="reference internal" href="../../documentation/start-documenting/#documenting"><span class="std std-ref">Getting started</span></a>.</p> <section id="install-pre-commit-as-a-git-hook"> <span id="install-pre-commit"></span><h3>Install pre-commit as a Git hook<a class="headerlink" href="#install-pre-commit-as-a-git-hook" title="Link to this heading">¶</a></h3> <p>To make sure your code is linted correctly, we recommend setting up <a class="reference external" href="https://pre-commit.com#installation">pre-commit</a> as a Git hook:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>pre-commit<span class="w"> </span>install<span class="w"> </span>--allow-missing-config <span class="go">pre-commit installed at .git/hooks/pre-commit</span> </pre></div> </div> <p>Now pre-commit will run automatically on <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span></code>.</p> </section> </section> <section id="compile-and-build"> <span id="compiling"></span><h2>Compile and build<a class="headerlink" href="#compile-and-build" title="Link to this heading">¶</a></h2> <p>CPython provides several compilation flags which help with debugging various things. While all of the known flags can be found in the <code class="docutils literal notranslate"><span class="pre">Misc/SpecialBuilds.txt</span></code> file, the most critical one is the <code class="docutils literal notranslate"><span class="pre">Py_DEBUG</span></code> flag which creates what is known as a “pydebug” build. This flag turns on various extra sanity checks which help catch common issues. The use of the flag is so common that turning on the flag is a basic compile option.</p> <p>You should always develop under a pydebug build of CPython (the only instance of when you shouldn’t is if you are taking performance measurements). Even when working only on pure Python code the pydebug build provides several useful checks that one should not skip.</p> <div class="admonition seealso"> <p class="admonition-title">See also</p> <p>The effects of various configure and build flags are documented in the <a class="reference external" href="https://docs.python.org/dev/using/configure.html">Python configure docs</a>.</p> </div> <section id="unix"> <span id="unix-compiling"></span><h3>Unix<a class="headerlink" href="#unix" title="Link to this heading">¶</a></h3> <p>The core CPython interpreter only needs a C compiler to be built, however, some of the extension modules will need development headers for additional libraries (such as the <code class="docutils literal notranslate"><span class="pre">zlib</span></code> library for compression). Depending on what you intend to work on, you might need to install these additional requirements so that the compiled interpreter supports the desired features.</p> <p>If you want to install these optional dependencies, consult the <a class="reference internal" href="#build-dependencies"><span class="std std-ref">Install dependencies</span></a> section below.</p> <p>If you don’t need to install them, the basic steps for building Python for development is to configure it and then compile it.</p> <p>Configuration is typically:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>./configure<span class="w"> </span>--with-pydebug </pre></div> </div> <p>More flags are available to <code class="docutils literal notranslate"><span class="pre">configure</span></code>, but this is the minimum you should do to get a pydebug build of CPython.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>You might need to run <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">clean</span></code> before or after re-running <code class="docutils literal notranslate"><span class="pre">configure</span></code> in a particular build directory.</p> </div> <p>Once <code class="docutils literal notranslate"><span class="pre">configure</span></code> is done, you can then compile CPython with:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>make<span class="w"> </span>-s<span class="w"> </span>-j2 </pre></div> </div> <p>This will build CPython with only warnings and errors being printed to stderr and utilize up to 2 CPU cores. If you are using a multi-core machine with more than 2 cores (or a single-core machine), you can adjust the number passed into the <code class="docutils literal notranslate"><span class="pre">-j</span></code> flag to match the number of cores you have (or if your version of Make supports it, you can use <code class="docutils literal notranslate"><span class="pre">-j</span></code> without a number and Make will not limit the number of steps that can run simultaneously.).</p> <p>At the end of the build you should see a success message, followed by a list of extension modules that haven’t been built because their dependencies were missing:</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>The necessary bits to build these optional modules were not found: _gdbm To find the necessary bits, look in configure.ac and config.log. Checked 106 modules (31 built-in, 74 shared, 0 n/a on macosx-13.4-arm64, 0 disabled, 1 missing, 0 failed on import) </pre></div> </div> <p>If the build failed and you are using a C89 or C99-compliant compiler, please open a bug report on the <a class="reference external" href="https://github.com/python/cpython/issues">issue tracker</a>.</p> <p>If you decide to <a class="reference internal" href="#build-dependencies"><span class="std std-ref">Install dependencies</span></a>, you will need to re-run both <code class="docutils literal notranslate"><span class="pre">configure</span></code> and <code class="docutils literal notranslate"><span class="pre">make</span></code>.</p> <p id="mac-python-exe">Once CPython is done building you will then have a working build that can be run in-place; <code class="docutils literal notranslate"><span class="pre">./python</span></code> on most machines (and what is used in all examples), <code class="docutils literal notranslate"><span class="pre">./python.exe</span></code> wherever a case-insensitive filesystem is used (for example, on macOS by default), in order to avoid conflicts with the <code class="docutils literal notranslate"><span class="pre">Python</span></code> directory. There is normally no need to install your built copy of Python! The interpreter will realize where it is being run from and thus use the files found in the working copy. If you are worried you might accidentally install your working copy build, you can add <code class="docutils literal notranslate"><span class="pre">--prefix=/tmp/python</span></code> to the configuration step. When running from your working directory, it is best to avoid using the <code class="docutils literal notranslate"><span class="pre">--enable-shared</span></code> flag to <code class="docutils literal notranslate"><span class="pre">configure</span></code>; unless you are very careful, you may accidentally run with code from an older, installed shared Python library rather than from the interpreter you just built.</p> <section id="clang"> <h4>Clang<a class="headerlink" href="#clang" title="Link to this heading">¶</a></h4> <p>If you are using <a class="reference external" href="https://clang.llvm.org/">clang</a> to build CPython, some flags you might want to set to quiet some standard warnings which are specifically superfluous to CPython are <code class="docutils literal notranslate"><span class="pre">-Wno-unused-value</span> <span class="pre">-Wno-empty-body</span> <span class="pre">-Qunused-arguments</span></code>. You can set your <code class="docutils literal notranslate"><span class="pre">CFLAGS</span></code> environment variable to these flags when running <code class="docutils literal notranslate"><span class="pre">configure</span></code>.</p> <p>If you are using <a class="reference external" href="https://clang.llvm.org/">clang</a> with <a class="reference external" href="https://ccache.dev/">ccache</a>, turn off the noisy <code class="docutils literal notranslate"><span class="pre">parentheses-equality</span></code> warnings with the <code class="docutils literal notranslate"><span class="pre">-Wno-parentheses-equality</span></code> flag. These warnings are caused by clang not having enough information to detect that extraneous parentheses in expanded macros are valid, because the preprocessing is done separately by ccache.</p> <p>If you are using LLVM 2.8, also use the <code class="docutils literal notranslate"><span class="pre">-no-integrated-as</span></code> flag in order to build the <a class="reference external" href="https://docs.python.org/3/library/ctypes.html#module-ctypes" title="(in Python v3.13)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">ctypes</span></code></a> module (without the flag the rest of CPython will still build properly).</p> </section> <section id="optimization"> <h4>Optimization<a class="headerlink" href="#optimization" title="Link to this heading">¶</a></h4> <p>If you are trying to improve CPython’s performance, you will probably want to use an optimized build of CPython. It can take a lot longer to build CPython with optimizations enabled, and it’s usually not necessary to do so. However, it’s essential if you want accurate benchmark results for a proposed performance optimization.</p> <p>For an optimized build of Python, use <code class="docutils literal notranslate"><span class="pre">configure</span> <span class="pre">--enable-optimizations</span> <span class="pre">--with-lto</span></code>. This sets the default make targets up to enable Profile Guided Optimization (PGO) and may be used to auto-enable Link Time Optimization (LTO) on some platforms. See <a class="reference external" href="https://docs.python.org/3/using/configure.html#cmdoption-enable-optimizations" title="(in Python v3.13)"><code class="docutils literal notranslate"><span class="pre">--enable-optimizations</span></code></a> and <a class="reference external" href="https://docs.python.org/3/using/configure.html#cmdoption-with-lto" title="(in Python v3.13)"><code class="docutils literal notranslate"><span class="pre">--with-lto</span></code></a> to learn more about these options.</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>./configure<span class="w"> </span>--enable-optimizations<span class="w"> </span>--with-lto </pre></div> </div> </section> </section> <section id="windows"> <span id="windows-compiling"></span><h3>Windows<a class="headerlink" href="#windows" title="Link to this heading">¶</a></h3> <div class="admonition note"> <p class="admonition-title">Note</p> <p>If you are using the Windows Subsystem for Linux (WSL), <a class="reference internal" href="#checkout"><span class="std std-ref">clone the repository</span></a> from a native Windows shell program like PowerShell or the <code class="docutils literal notranslate"><span class="pre">cmd.exe</span></code> command prompt, and use a build of Git targeted for Windows, for example, the <a class="reference external" href="https://git-scm.com/download/win">Git for Windows download from the official Git website</a>. Otherwise, Visual Studio will not be able to find all the project’s files and will fail the build.</p> </div> <p>For a concise step by step summary of building Python on Windows, you can read <a class="reference external" href="https://web.archive.org/web/20220907075854/https://cpython-core-tutorial.readthedocs.io/en/latest/build_cpython_windows.html">Victor Stinner’s guide</a>.</p> <p>All supported versions of Python can be built using Microsoft Visual Studio 2017 or later. You can download and use any of the free or paid versions of <a class="reference external" href="https://visualstudio.microsoft.com/">Visual Studio</a>.</p> <p>When installing it, select the <span class="guilabel">Python development</span> workload and the optional <span class="guilabel">Python native development tools</span> component to obtain all of the necessary build tools. You can find Git for Windows on the <span class="guilabel">Individual components</span> tab if you don’t already have it installed.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>If you want to build MSI installers, be aware that the build toolchain for them has a dependency on the Microsoft .NET Framework Version 3.5 (which may not be included on recent versions of Windows, such as Windows 10). If you are building on a recent Windows version, use the Control Panel (<span class="menuselection">Programs ‣ Programs and Features ‣ Turn Windows Features on or off</span>) and ensure that the entry <span class="guilabel">.NET Framework 3.5 (includes .NET 2.0 and 3.0)</span> is enabled.</p> </div> <p>Your first build should use the command line to ensure any external dependencies are downloaded:</p> <div class="highlight-batch notranslate"><div class="highlight"><pre><span></span>PCbuild\build.bat -c Debug </pre></div> </div> <p>The above command line build uses the <code class="docutils literal notranslate"><span class="pre">-c</span> <span class="pre">Debug</span></code> argument to build in the <code class="docutils literal notranslate"><span class="pre">Debug</span></code> configuration, which enables checks and assertions helpful for developing Python. By default, it builds in the <code class="docutils literal notranslate"><span class="pre">Release</span></code> configuration and for the 64-bit <code class="docutils literal notranslate"><span class="pre">x64</span></code> platform rather than 32-bit <code class="docutils literal notranslate"><span class="pre">Win32</span></code>; use <code class="docutils literal notranslate"><span class="pre">-c</span></code> and <code class="docutils literal notranslate"><span class="pre">-p</span></code> to control build config and platform, respectively.</p> <p>After this build succeeds, you can open the <code class="docutils literal notranslate"><span class="pre">PCbuild\pcbuild.sln</span></code> solution in the Visual Studio IDE to continue development, if you prefer. When building in Visual Studio, make sure to select build settings that match what you used with the script (the <span class="guilabel">Debug</span> configuration and the <span class="guilabel">x64</span> platform) from the dropdown menus in the toolbar.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>If you need to change the build configuration or platform, build once with the <code class="docutils literal notranslate"><span class="pre">build.bat</span></code> script set to those options first before building with them in VS to ensure all files are rebuilt properly, or you may encounter errors when loading modules that were not rebuilt.</p> <p>Avoid selecting the <code class="docutils literal notranslate"><span class="pre">PGInstrument</span></code> and <code class="docutils literal notranslate"><span class="pre">PGUpdate</span></code> configurations, as these are intended for PGO builds and not for normal development.</p> </div> <p>You can run the build of Python you’ve compiled with:</p> <div class="highlight-batch notranslate"><div class="highlight"><pre><span></span>PCbuild\amd64\python_d.exe </pre></div> </div> <p>See the <a class="reference external" href="https://github.com/python/cpython/blob/main/PCbuild/readme.txt">PCBuild readme</a> for more details on what other software is necessary and how to build.</p> </section> <section id="wasi"> <span id="wasi-compiling"></span><h3>WASI<a class="headerlink" href="#wasi" title="Link to this heading">¶</a></h3> <p><a class="reference external" href="https://wasi.dev">WASI</a> is a system interface standard for <a class="reference external" href="https://webassembly.org">WebAssembly</a>. Through a combination of C compilers that can target WebAssembly and <a class="reference external" href="https://github.com/WebAssembly/wasi-libc">wasi-libc</a> providing POSIX-compatible shims for WASI, it’s possible for CPython to run on a WASI host/runtime as a <em>guest</em>.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>The instructions below assume a Unix-based OS due to cross-compilation for CPython being designed for <code class="docutils literal notranslate"><span class="pre">./configure</span></code> / <code class="docutils literal notranslate"><span class="pre">make</span></code>.</p> </div> <p>To build for WASI, you will need to cross-compile CPython. This requires a C compiler just like building for <a class="reference internal" href="#unix-compiling"><span class="std std-ref">Unix</span></a> as well as:</p> <ol class="arabic simple"> <li><p>A C compiler that can target WebAssembly (for example, <a class="reference external" href="https://github.com/WebAssembly/wasi-sdk">WASI SDK</a>)</p></li> <li><p>A WASI host/runtime (for example, <a class="reference external" href="https://wasmtime.dev">Wasmtime</a>)</p></li> </ol> <p>All of this is provided in the <a class="reference internal" href="#using-codespaces"><span class="std std-ref">devcontainer</span></a>. You can also use what’s installed in the container as a reference of what versions of these tools are known to work.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>CPython has only been verified with the above tools for WASI. Using other compilers, hosts, or WASI versions <em>should</em> work, but the above tools and their versions specified in the container are tested via a <a class="reference internal" href="../../testing/buildbots/#buildbots"><span class="std std-ref">buildbot</span></a>.</p> </div> <p>Building for WASI requires doing a cross-build where you have a <em>build</em> Python to help produce a WASI build of CPython (technically it’s a “host x host” cross-build because the build Python is also the target Python while the host build is the WASI build). This means you effectively build CPython twice: once to have a version of Python for the build system to use and another that’s the build you ultimately care about (that is, the build Python is not meant for use by you directly, only the build system).</p> <p>The easiest way to get a debug build of CPython for WASI is to use the <code class="docutils literal notranslate"><span class="pre">Tools/wasm/wasi.py</span> <span class="pre">build</span></code> command (which should be run w/ a recent version of Python you have installed on your machine):</p> <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>python3<span class="w"> </span>Tools/wasm/wasi.py<span class="w"> </span>build<span class="w"> </span>--quiet<span class="w"> </span>--<span class="w"> </span>--config-cache<span class="w"> </span>--with-pydebug </pre></div> </div> <p>That single command will configure and build both the build Python and the WASI build in <code class="docutils literal notranslate"><span class="pre">cross-build/build</span></code> and <code class="docutils literal notranslate"><span class="pre">cross-build/wasm32-wasi</span></code>, respectively.</p> <p>You can also do each configuration and build step separately; the command above is a convenience wrapper around the following commands:</p> <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>python<span class="w"> </span>Tools/wasm/wasi.py<span class="w"> </span>configure-build-python<span class="w"> </span>--quiet<span class="w"> </span>--<span class="w"> </span>--config-cache<span class="w"> </span>--with-pydebug $<span class="w"> </span>python<span class="w"> </span>Tools/wasm/wasi.py<span class="w"> </span>make-build-python<span class="w"> </span>--quiet $<span class="w"> </span>python<span class="w"> </span>Tools/wasm/wasi.py<span class="w"> </span>configure-host<span class="w"> </span>--quiet<span class="w"> </span>--<span class="w"> </span>--config-cache $<span class="w"> </span>python<span class="w"> </span>Tools/wasm/wasi.py<span class="w"> </span>make-host<span class="w"> </span>--quiet </pre></div> </div> <div class="admonition note"> <p class="admonition-title">Note</p> <p>The <code class="docutils literal notranslate"><span class="pre">configure-host</span></code> command infers the use of <code class="docutils literal notranslate"><span class="pre">--with-pydebug</span></code> from the build Python.</p> </div> <p>Running the separate commands after <code class="docutils literal notranslate"><span class="pre">wasi.py</span> <span class="pre">build</span></code> is useful if you, for example, only want to run the <code class="docutils literal notranslate"><span class="pre">make-host</span></code> step after making code changes.</p> <p>Once everything is complete, there will be a <code class="docutils literal notranslate"><span class="pre">cross-build/wasm32-wasi/python.sh</span></code> helper file which you can use to run the <code class="docutils literal notranslate"><span class="pre">python.wasm</span></code> file (see the output from the <code class="docutils literal notranslate"><span class="pre">configure-host</span></code> subcommand):</p> <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>cross-build/wasm32-wasi/python.sh<span class="w"> </span>--version </pre></div> </div> <p>You can also use <code class="docutils literal notranslate"><span class="pre">Makefile</span></code> targets and they will work as expected thanks to the <code class="docutils literal notranslate"><span class="pre">HOSTRUNNER</span></code> environment variable having been set to a similar value as used in <code class="docutils literal notranslate"><span class="pre">python.sh</span></code>:</p> <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>-C<span class="w"> </span>cross-build/wasm32-wasi<span class="w"> </span><span class="nb">test</span> </pre></div> </div> <div class="admonition note"> <p class="admonition-title">Note</p> <p>WASI uses a <em>capability-based</em> security model. This means that the WASI host does not give full access to your machine unless you tell it to. This also means things like files can end up being mapped to a different path inside the WASI host. So, if you try passing a file path to <code class="docutils literal notranslate"><span class="pre">python.wasm</span></code>/ <code class="docutils literal notranslate"><span class="pre">python.sh</span></code>, it needs to match the path <strong>inside</strong> the WASI host, not the path on your machine (much like using a container).</p> </div> </section> <section id="emscripten"> <h3>Emscripten<a class="headerlink" href="#emscripten" title="Link to this heading">¶</a></h3> <p><a class="reference external" href="https://emscripten.org/">Emscripten</a> is a complete open-source compiler toolchain. It compiles C/C++ code into <a class="reference external" href="https://webassembly.org">WebAssembly</a>/JavaScript executables, for use in JavaScript runtimes, including browsers and Node.js.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>The instructions below assume a Unix-based OS due to cross-compilation for CPython being designed for <code class="docutils literal notranslate"><span class="pre">./configure</span></code> / <code class="docutils literal notranslate"><span class="pre">make</span></code>.</p> </div> <p>To build for Emscripten, you will need to cross-compile CPython. This requires a C compiler just like building for <a class="reference internal" href="#unix-compiling"><span class="std std-ref">Unix</span></a> as well as:</p> <ul class="simple"> <li><p>The Emscripten compiler</p></li> <li><p>Node.js</p></li> </ul> <p>The simplest way to install the Emscripten compiler is:</p> <div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install Emscripten</span> git<span class="w"> </span>clone<span class="w"> </span>https://github.com/emscripten-core/emsdk ./emsdk/emsdk<span class="w"> </span>install<span class="w"> </span><span class="m">4</span>.0.5 ./emsdk/emsdk<span class="w"> </span>activate<span class="w"> </span><span class="m">4</span>.0.5 <span class="nb">source</span><span class="w"> </span>./emsdk/emsdk_env.sh </pre></div> </div> <p>Updating the Emscripten compiler version often causes breakages. For the best compatibility, use the Emscripten version suggested in the cpython repository in <code class="docutils literal notranslate"><span class="pre">Tools/wasm/README.md</span></code>.</p> <p>Building for Emscripten requires doing a cross-build where you have a <em>build</em> Python to help produce an Emscripten build of CPython. This means you build CPython twice: once to have a version of Python for the build system to use and another that’s the build you ultimately care about (that is, the build Python is not meant for use by you directly, only the build system).</p> <p>The easiest way to get a debug build of CPython for Emscripten is to use the <code class="docutils literal notranslate"><span class="pre">Tools/wasm/emscripten</span> <span class="pre">build</span></code> command (which should be run with a recent version of Python you have installed on your machine):</p> <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>python3<span class="w"> </span>Tools/wasm/emscripten<span class="w"> </span>build<span class="w"> </span>--quiet<span class="w"> </span>--<span class="w"> </span>--config-cache<span class="w"> </span>--with-pydebug </pre></div> </div> <p>That single command will configure and build both the build Python and the Emscripten build in <code class="docutils literal notranslate"><span class="pre">cross-build/build</span></code> and <code class="docutils literal notranslate"><span class="pre">cross-build/wasm32-emscripten/build/python/</span></code>, respectively.</p> <p>You can also do each configuration and build step separately; the command above is a convenience wrapper around the following commands:</p> <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>python<span class="w"> </span>Tools/wasm/emscripten<span class="w"> </span>configure-build-python<span class="w"> </span>--quiet<span class="w"> </span>--<span class="w"> </span>--config-cache<span class="w"> </span>--with-pydebug python<span class="w"> </span>Tools/wasm/emscripten<span class="w"> </span>make-build-python<span class="w"> </span>--quiet python<span class="w"> </span>Tools/wasm/emscripten<span class="w"> </span>make-libffi<span class="w"> </span>--quiet python<span class="w"> </span>Tools/wasm/emscripten<span class="w"> </span>configure-host<span class="w"> </span>--quiet<span class="w"> </span>--<span class="w"> </span>--config-cache python<span class="w"> </span>Tools/wasm/emscripten<span class="w"> </span>make-host<span class="w"> </span>--quiet </pre></div> </div> <div class="admonition note"> <p class="admonition-title">Note</p> <p>The <code class="docutils literal notranslate"><span class="pre">configure-host</span></code> command infers the use of <code class="docutils literal notranslate"><span class="pre">--with-pydebug</span></code> from the build Python.</p> </div> <p>Running the separate commands after <code class="docutils literal notranslate"><span class="pre">emscripten</span> <span class="pre">build</span></code> is useful if you, for example, only want to run the <code class="docutils literal notranslate"><span class="pre">make-host</span></code> step after making code changes.</p> <p>Once everything is complete, there will be a <code class="docutils literal notranslate"><span class="pre">cross-build/wasm32-emscripten/build/python/python.sh</span></code> helper file which you can use to run the <code class="docutils literal notranslate"><span class="pre">python.mjs</span></code> file:</p> <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>cross-build/wasm32-emscripten/build/python/python.sh<span class="w"> </span>--version </pre></div> </div> <p>You can also use <code class="docutils literal notranslate"><span class="pre">Makefile</span></code> targets and they will work as expected thanks to the <code class="docutils literal notranslate"><span class="pre">HOSTRUNNER</span></code> environment variable having been set to a similar value as used in <code class="docutils literal notranslate"><span class="pre">python.sh</span></code>:</p> <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>make<span class="w"> </span>-C<span class="w"> </span>cross-build/wasm32-emscripten/build/python/<span class="w"> </span><span class="nb">test</span> </pre></div> </div> </section> <section id="android"> <h3>Android<a class="headerlink" href="#android" title="Link to this heading">¶</a></h3> <p>Build and test instructions for Android are maintained in the CPython repository at <a class="extlink-cpy-file reference external" href="https://github.com/python/cpython/blob/main/Android/README.md">Android/README.md</a>.</p> </section> <section id="ios"> <h3>iOS<a class="headerlink" href="#ios" title="Link to this heading">¶</a></h3> <p>Compiling Python for iOS requires a macOS machine, on a recent version of macOS, running a recent version of Xcode. Apple expects developers to keep their operating systems and tools up-to-date; if your macOS version is more than one major release out of date, or your Xcode version is more than a couple of minor versions out of date, you’ll likely encounter difficulties. It is not possible to compile for iOS using Windows or Linux as a build machine.</p> <p>A complete build for Python on iOS requires compiling CPython four times: once for macOS; then once for each of the three underlying platforms used by iOS:</p> <ul class="simple"> <li><p>An ARM64 device (an iPhone or iPad);</p></li> <li><p>An ARM64 simulator running on a recent macOS machine; and</p></li> <li><p>An x86_64 simulator running on older macOS machine.</p></li> </ul> <p>The macOS build is required because building Python involves running some Python code. On a normal desktop build of Python, you can compile a Python interpreter and then use that interpreter to run Python code. However, the binaries produced for iOS won’t run on macOS, so you need to provide an external Python interpreter. From the root of a CPython code checkout, run the following:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>./configure<span class="w"> </span>--prefix<span class="o">=</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span>/cross-build/macOS <span class="gp">$ </span>make<span class="w"> </span>-j4<span class="w"> </span>all <span class="gp">$ </span>make<span class="w"> </span>install </pre></div> </div> <p>This will build and install Python for macOS into the <code class="docutils literal notranslate"><span class="pre">cross-build/macOS</span></code> directory.</p> <p>The CPython build system can compile a single platform at a time. It is possible to <em>test</em> a single platform at a time; however, for distribution purposes, you must compile all three, and merge the results. See the <a class="reference external" href="https://github.com/python/cpython/blob/main/iOS/README.rst#merge-thin-frameworks-into-fat-frameworks">iOS README</a> for details on this merging process.</p> <p>The following instructions will build CPython for iOS with all extensions enabled, provided you have installed the build dependencies XZ, BZip2, OpenSSL and libFFI in subfolders of the <code class="docutils literal notranslate"><span class="pre">cross-build</span></code> folder. See <a class="reference internal" href="#build-dependencies"><span class="std std-ref">the iOS section on installing build dependencies</span></a> for details on how to obtain these dependencies. These dependencies are all strictly optional, however, including libFFI is <em>highly</em> recommended, as it is required by the <a class="reference external" href="https://docs.python.org/3/library/ctypes.html#module-ctypes" title="(in Python v3.13)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">ctypes</span></code></a> module which is used on iOS to support accessing native system APIs.</p> <div class="tab-set docutils container"> <input checked="True" class="tab-input" id="tab-set--0-input--1" name="tab-set--0" type="radio"><label class="tab-label" for="tab-set--0-input--1">ARM64 device</label><div class="tab-content docutils container"> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nb">export</span><span class="w"> </span><span class="nv">PATH</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span><span class="s2">/iOS/Resources/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Library/Apple/usr/bin"</span> <span class="gp">$ </span>./configure<span class="w"> </span><span class="se">\</span> <span class="w"> </span><span class="nv">LIBLZMA_CFLAGS</span><span class="o">=</span><span class="s2">"-I</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span><span class="s2">/cross-build/iphoneos.arm64/xz/include"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span><span class="nv">LIBLZMA_LIBS</span><span class="o">=</span><span class="s2">"-L</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span><span class="s2">/cross-build/iphoneos.arm64/xz/lib -llzma"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span><span class="nv">BZIP2_CFLAGS</span><span class="o">=</span><span class="s2">"-I</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span><span class="s2">/cross-build/iphoneos.arm64/bzip2/include"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span><span class="nv">BZIP2_LIBS</span><span class="o">=</span><span class="s2">"-L</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span><span class="s2">/cross-build/iphoneos.arm64/bzip2/lib -lbz2"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span><span class="nv">LIBFFI_CFLAGS</span><span class="o">=</span><span class="s2">"-I</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span><span class="s2">/cross-build/iphoneos.arm64/libffi/include"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span><span class="nv">LIBFFI_LIBS</span><span class="o">=</span><span class="s2">"-L</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span><span class="s2">/cross-build/iphoneos.arm64/libffi/lib -lffi"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span>--with-openssl<span class="o">=</span><span class="s2">"</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span><span class="s2">/cross-build/iphoneos.arm64/openssl"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span>--host<span class="o">=</span>arm64-apple-ios12.0<span class="w"> </span><span class="se">\</span> <span class="w"> </span>--build<span class="o">=</span>arm64-apple-darwin<span class="w"> </span><span class="se">\</span> <span class="w"> </span>--with-build-python<span class="o">=</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span>/cross-build/macOS/bin/python3.13<span class="w"> </span><span class="se">\</span> <span class="w"> </span>--enable-framework <span class="gp">$ </span>make<span class="w"> </span>-j4<span class="w"> </span>all <span class="gp">$ </span>make<span class="w"> </span>install </pre></div> </div> </div> <input class="tab-input" id="tab-set--0-input--2" name="tab-set--0" type="radio"><label class="tab-label" for="tab-set--0-input--2">ARM64 simulator</label><div class="tab-content docutils container"> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nb">export</span><span class="w"> </span><span class="nv">PATH</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span><span class="s2">/iOS/Resources/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Library/Apple/usr/bin"</span> <span class="gp">$ </span>./configure<span class="w"> </span><span class="se">\</span> <span class="w"> </span><span class="nv">LIBLZMA_CFLAGS</span><span class="o">=</span><span class="s2">"-I</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span><span class="s2">/cross-build/iphonesimulator.arm64/xz/include"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span><span class="nv">LIBLZMA_LIBS</span><span class="o">=</span><span class="s2">"-L</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span><span class="s2">/cross-build/iphonesimulator.arm64/xz/lib -llzma"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span><span class="nv">BZIP2_CFLAGS</span><span class="o">=</span><span class="s2">"-I</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span><span class="s2">/cross-build/iphonesimulator.arm64/bzip2/include"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span><span class="nv">BZIP2_LIBS</span><span class="o">=</span><span class="s2">"-L</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span><span class="s2">/cross-build/iphonesimulator.arm64/bzip2/lib -lbz2"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span><span class="nv">LIBFFI_CFLAGS</span><span class="o">=</span><span class="s2">"-I</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span><span class="s2">/cross-build/iphonesimulator.arm64/libffi/include"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span><span class="nv">LIBFFI_LIBS</span><span class="o">=</span><span class="s2">"-L</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span><span class="s2">/cross-build/iphonesimulator.arm64/libffi/lib -lffi"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span>--with-openssl<span class="o">=</span><span class="s2">"</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span><span class="s2">/cross-build/iphonesimulator.arm64/openssl"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span>--host<span class="o">=</span>arm64-apple-ios12.0-simulator<span class="w"> </span><span class="se">\</span> <span class="w"> </span>--build<span class="o">=</span>arm64-apple-darwin<span class="w"> </span><span class="se">\</span> <span class="w"> </span>--with-build-python<span class="o">=</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span>/cross-build/macOS/bin/python3.13<span class="w"> </span><span class="se">\</span> <span class="w"> </span>--enable-framework <span class="gp">$ </span>make<span class="w"> </span>-j4<span class="w"> </span>all <span class="gp">$ </span>make<span class="w"> </span>install </pre></div> </div> </div> <input class="tab-input" id="tab-set--0-input--3" name="tab-set--0" type="radio"><label class="tab-label" for="tab-set--0-input--3">x86-64 simulator</label><div class="tab-content docutils container"> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nb">export</span><span class="w"> </span><span class="nv">PATH</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span><span class="s2">/iOS/Resources/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Library/Apple/usr/bin"</span> <span class="gp">$ </span>./configure<span class="w"> </span><span class="se">\</span> <span class="w"> </span><span class="nv">LIBLZMA_CFLAGS</span><span class="o">=</span><span class="s2">"-I</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span><span class="s2">/cross-build/iphonesimulator.x86_64/xz/include"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span><span class="nv">LIBLZMA_LIBS</span><span class="o">=</span><span class="s2">"-L</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span><span class="s2">/cross-build/iphonesimulator.x86_64/xz/lib -llzma"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span><span class="nv">BZIP2_CFLAGS</span><span class="o">=</span><span class="s2">"-I</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span><span class="s2">/cross-build/iphonesimulator.x86_64/bzip2/include"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span><span class="nv">BZIP2_LIBS</span><span class="o">=</span><span class="s2">"-L</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span><span class="s2">/cross-build/iphonesimulator.x86_64/bzip2/lib -lbz2"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span><span class="nv">LIBFFI_CFLAGS</span><span class="o">=</span><span class="s2">"-I</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span><span class="s2">/cross-build/iphonesimulator.x86_64/libffi/include"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span><span class="nv">LIBFFI_LIBS</span><span class="o">=</span><span class="s2">"-L</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span><span class="s2">/cross-build/iphonesimulator.x86_64/libffi/lib -lffi"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span>--with-openssl<span class="o">=</span><span class="s2">"</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span><span class="s2">/cross-build/iphonesimulator.x86_64/openssl"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span>--host<span class="o">=</span>x86_64-apple-ios12.0-simulator<span class="w"> </span><span class="se">\</span> <span class="w"> </span>--build<span class="o">=</span>arm64-apple-darwin<span class="w"> </span><span class="se">\</span> <span class="w"> </span>--with-build-python<span class="o">=</span><span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span>/cross-build/macOS/bin/python3.13<span class="w"> </span><span class="se">\</span> <span class="w"> </span>--enable-framework <span class="gp">$ </span>make<span class="w"> </span>-j4<span class="w"> </span>all <span class="gp">$ </span>make<span class="w"> </span>install </pre></div> </div> </div> </div> <p>These instructions modify your <code class="docutils literal notranslate"><span class="pre">PATH</span></code> before the build. As iOS and macOS share a hardware architecture (ARM64), it is easy for a macOS ARM64 binary to be accidentally linked into your iOS build. This is especially common when Homebrew is present on the build system. The most reliable way to avoid this problem is to remove any potential source of other libraries from your <code class="docutils literal notranslate"><span class="pre">PATH</span></code>.</p> <p>However, the <code class="docutils literal notranslate"><span class="pre">PATH</span></code> is not completely bare — it includes the <code class="docutils literal notranslate"><span class="pre">iOS/Resources/bin</span></code> folder. This folder contains a collection of scripts that wrap the invocation of the Xcode <strong class="program">xcrun</strong> tool, removing user- and version-specific paths from the values encoded in the <a class="reference external" href="https://docs.python.org/3/library/sysconfig.html#module-sysconfig" title="(in Python v3.13)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sysconfig</span></code></a> module. Copies of these scripts are included in the final build products.</p> <p>Once this build completes, the <code class="docutils literal notranslate"><span class="pre">iOS/Frameworks</span></code> folder will contain a <code class="docutils literal notranslate"><span class="pre">Python.framework</span></code> that can be used for testing.</p> <p>To run the test suite on iOS, complete a build for a <em>simulator</em> platform, ensure the path modifications from the build are still in effect, and run:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>make<span class="w"> </span>testios </pre></div> </div> <p>The full test suite takes approximately 12 minutes to run on a 2022 M1 MacBook Pro, plus a couple of extra minutes to build the testbed application and boot the simulator. There will be an initial burst of console output while the Xcode test project is compiled; however, while the test suite is running, there is no console output or progress. This is a side effect of how Xcode operates when executed at the command line. You should see an iOS simulator appear during the testing process; the simulator will booth to an iOS landing screen, the testbed app will be installed, and then started. The screen of the simulator will be black while the test suite is running. When the test suite completes, success or failure will be reported at the command line. In the case of failure, you will see the full log of CPython test suite output.</p> <p>You can also run the test suite in Xcode itself. This is required if you want to run on a physical device; it is also the easiest approach if you need to run a single test, or a subset of tests. See the <a class="reference external" href="https://github.com/python/cpython/blob/main/iOS/README.rst#debugging-test-failures">iOS README</a> for details.</p> </section> </section> <section id="install-dependencies"> <span id="macos"></span><span id="macos-and-os-x"></span><span id="deps-on-linux"></span><span id="build-dependencies"></span><h2>Install dependencies<a class="headerlink" href="#install-dependencies" title="Link to this heading">¶</a></h2> <p>This section explains how to install libraries which are needed to compile some of CPython’s modules (for example, <code class="docutils literal notranslate"><span class="pre">zlib</span></code>).</p> <div class="tab-set docutils container"> <input checked="True" class="tab-input" id="tab-set--4-input--1" name="tab-set--4" type="radio"><label class="tab-label" for="tab-set--4-input--1">Linux</label><div class="tab-content docutils container"> <p>For Unix-based systems, we try to use system libraries whenever available. This means optional components will only build if the relevant system headers are available. The best way to obtain the appropriate headers will vary by distribution, but the appropriate commands for some popular distributions are below.</p> <p>On <strong>Fedora</strong>, <strong>RHEL</strong>, <strong>CentOS</strong> and other <code class="docutils literal notranslate"><span class="pre">dnf</span></code>-based systems:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>sudo<span class="w"> </span>dnf<span class="w"> </span>install<span class="w"> </span>git<span class="w"> </span>pkg-config <span class="gp">$ </span>sudo<span class="w"> </span>dnf<span class="w"> </span>install<span class="w"> </span>dnf-plugins-core<span class="w"> </span><span class="c1"># install this to use 'dnf builddep'</span> <span class="gp">$ </span>sudo<span class="w"> </span>dnf<span class="w"> </span>builddep<span class="w"> </span>python3 </pre></div> </div> <p>Some optional development dependencies are not included in the above. To install some additional dependencies for optional build and test components:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>sudo<span class="w"> </span>dnf<span class="w"> </span>install<span class="w"> </span><span class="se">\</span> <span class="w"> </span>gcc<span class="w"> </span>gcc-c++<span class="w"> </span>gdb<span class="w"> </span>lzma<span class="w"> </span>glibc-devel<span class="w"> </span>libstdc++-devel<span class="w"> </span>openssl-devel<span class="w"> </span><span class="se">\</span> <span class="w"> </span>readline-devel<span class="w"> </span>zlib-devel<span class="w"> </span>libffi-devel<span class="w"> </span>bzip2-devel<span class="w"> </span>xz-devel<span class="w"> </span><span class="se">\</span> <span class="w"> </span>sqlite<span class="w"> </span>sqlite-devel<span class="w"> </span>sqlite-libs<span class="w"> </span>libuuid-devel<span class="w"> </span>gdbm-libs<span class="w"> </span>perf<span class="w"> </span><span class="se">\</span> <span class="w"> </span>expat<span class="w"> </span>expat-devel<span class="w"> </span>mpdecimal<span class="w"> </span>python3-pip </pre></div> </div> <p>On <strong>Debian</strong>, <strong>Ubuntu</strong>, and other <code class="docutils literal notranslate"><span class="pre">apt</span></code>-based systems, try to get the dependencies for the Python you’re working on by using the <code class="docutils literal notranslate"><span class="pre">apt</span></code> command.</p> <p>First, make sure you have enabled the source packages in the sources list. You can do this by adding the location of the source packages, including URL, distribution name and component name, to <code class="docutils literal notranslate"><span class="pre">/etc/apt/sources.list</span></code>. Take Ubuntu 22.04 LTS (Jammy Jellyfish) for example:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>deb-src<span class="w"> </span>http://archive.ubuntu.com/ubuntu/<span class="w"> </span>jammy<span class="w"> </span>main </pre></div> </div> <p>Alternatively, uncomment lines with <code class="docutils literal notranslate"><span class="pre">deb-src</span></code> using an editor, for example:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>sudo<span class="w"> </span>nano<span class="w"> </span>/etc/apt/sources.list </pre></div> </div> <p>For other distributions, like Debian, change the URL and names to correspond with the specific distribution.</p> <p>Then you should update the packages index:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>sudo<span class="w"> </span>apt-get<span class="w"> </span>update </pre></div> </div> <p>Now you can install the build dependencies via <code class="docutils literal notranslate"><span class="pre">apt</span></code>:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>sudo<span class="w"> </span>apt-get<span class="w"> </span>build-dep<span class="w"> </span>python3 <span class="gp">$ </span>sudo<span class="w"> </span>apt-get<span class="w"> </span>install<span class="w"> </span>pkg-config </pre></div> </div> <p>If you want to build all optional modules, install the following packages and their dependencies:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>sudo<span class="w"> </span>apt-get<span class="w"> </span>install<span class="w"> </span>build-essential<span class="w"> </span>gdb<span class="w"> </span>lcov<span class="w"> </span>pkg-config<span class="w"> </span><span class="se">\</span> <span class="w"> </span>libbz2-dev<span class="w"> </span>libffi-dev<span class="w"> </span>libgdbm-dev<span class="w"> </span>libgdbm-compat-dev<span class="w"> </span>liblzma-dev<span class="w"> </span><span class="se">\</span> <span class="w"> </span>libncurses5-dev<span class="w"> </span>libreadline6-dev<span class="w"> </span>libsqlite3-dev<span class="w"> </span>libssl-dev<span class="w"> </span><span class="se">\</span> <span class="w"> </span>lzma<span class="w"> </span>lzma-dev<span class="w"> </span>tk-dev<span class="w"> </span>uuid-dev<span class="w"> </span>zlib1g-dev<span class="w"> </span>libmpdec-dev </pre></div> </div> <p>Note that Debian 12 and Ubuntu 24.04 do not have the <code class="docutils literal notranslate"><span class="pre">libmpdec-dev</span></code> package. You can safely remove it from the install list above and the Python build will use a bundled version.</p> </div> <input class="tab-input" id="tab-set--4-input--2" name="tab-set--4" type="radio"><label class="tab-label" for="tab-set--4-input--2">macOS</label><div class="tab-content docutils container"> <p>For <strong>macOS systems</strong> (versions 10.9+), the Developer Tools can be downloaded and installed automatically; you do not need to download the complete Xcode application.</p> <p>If necessary, run the following:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>xcode-select<span class="w"> </span>--install </pre></div> </div> <p>This will also ensure that the system header files are installed into <code class="docutils literal notranslate"><span class="pre">/usr/include</span></code>.</p> <p>Also note that macOS does not include several libraries used by the Python standard library, including <code class="docutils literal notranslate"><span class="pre">libzma</span></code>, so expect to see some extension module build failures unless you install local copies of them. As of OS X 10.11, Apple no longer provides header files for the deprecated system version of OpenSSL which means that you will not be able to build the <code class="docutils literal notranslate"><span class="pre">_ssl</span></code> extension. One solution is to install these libraries from a third-party package manager, like <a class="reference external" href="https://brew.sh">Homebrew</a> or <a class="reference external" href="https://www.macports.org">MacPorts</a>, and then add the appropriate paths for the header and library files to your <code class="docutils literal notranslate"><span class="pre">configure</span></code> command.</p> <div class="tab-set docutils container"> <input checked="True" class="tab-input" id="tab-set--3-input--1" name="tab-set--3" type="radio"><label class="tab-label" for="tab-set--3-input--1">Homebrew</label><div class="tab-content docutils container"> <p>For <strong>Homebrew</strong>, install dependencies using <code class="docutils literal notranslate"><span class="pre">brew</span></code>:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>brew<span class="w"> </span>install<span class="w"> </span>pkg-config<span class="w"> </span>openssl@3<span class="w"> </span>xz<span class="w"> </span>gdbm<span class="w"> </span>tcl-tk<span class="w"> </span>mpdecimal </pre></div> </div> <div class="tab-set docutils container"> <input checked="True" class="tab-input" id="tab-set--1-input--1" name="tab-set--1" type="radio"><label class="tab-label" for="tab-set--1-input--1">Python 3.13+</label><div class="tab-content docutils container"> <p>For Python 3.13 and newer:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nv">GDBM_CFLAGS</span><span class="o">=</span><span class="s2">"-I</span><span class="k">$(</span>brew<span class="w"> </span>--prefix<span class="w"> </span>gdbm<span class="k">)</span><span class="s2">/include"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span><span class="nv">GDBM_LIBS</span><span class="o">=</span><span class="s2">"-L</span><span class="k">$(</span>brew<span class="w"> </span>--prefix<span class="w"> </span>gdbm<span class="k">)</span><span class="s2">/lib -lgdbm"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span>./configure<span class="w"> </span>--with-pydebug<span class="w"> </span><span class="se">\</span> <span class="w"> </span>--with-system-libmpdec<span class="w"> </span><span class="se">\</span> <span class="w"> </span>--with-openssl<span class="o">=</span><span class="s2">"</span><span class="k">$(</span>brew<span class="w"> </span>--prefix<span class="w"> </span>openssl@3<span class="k">)</span><span class="s2">"</span> </pre></div> </div> </div> <input class="tab-input" id="tab-set--1-input--2" name="tab-set--1" type="radio"><label class="tab-label" for="tab-set--1-input--2">Python 3.11-3.12</label><div class="tab-content docutils container"> <p>For Python 3.11 and 3.12:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nv">GDBM_CFLAGS</span><span class="o">=</span><span class="s2">"-I</span><span class="k">$(</span>brew<span class="w"> </span>--prefix<span class="w"> </span>gdbm<span class="k">)</span><span class="s2">/include"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span><span class="nv">GDBM_LIBS</span><span class="o">=</span><span class="s2">"-L</span><span class="k">$(</span>brew<span class="w"> </span>--prefix<span class="w"> </span>gdbm<span class="k">)</span><span class="s2">/lib -lgdbm"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span>./configure<span class="w"> </span>--with-pydebug<span class="w"> </span><span class="se">\</span> <span class="w"> </span>--with-openssl<span class="o">=</span><span class="s2">"</span><span class="k">$(</span>brew<span class="w"> </span>--prefix<span class="w"> </span>openssl@3<span class="k">)</span><span class="s2">"</span> </pre></div> </div> </div> <input class="tab-input" id="tab-set--1-input--3" name="tab-set--1" type="radio"><label class="tab-label" for="tab-set--1-input--3">Python 3.9-3.10</label><div class="tab-content docutils container"> <p>For Python 3.9 and 3.10:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nv">CPPFLAGS</span><span class="o">=</span><span class="s2">"-I</span><span class="k">$(</span>brew<span class="w"> </span>--prefix<span class="w"> </span>gdbm<span class="k">)</span><span class="s2">/include -I</span><span class="k">$(</span>brew<span class="w"> </span>--prefix<span class="w"> </span>xz<span class="k">)</span><span class="s2">/include"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span><span class="nv">LDFLAGS</span><span class="o">=</span><span class="s2">"-L</span><span class="k">$(</span>brew<span class="w"> </span>--prefix<span class="w"> </span>gdbm<span class="k">)</span><span class="s2">/lib -L</span><span class="k">$(</span>brew<span class="w"> </span>--prefix<span class="w"> </span>xz<span class="k">)</span><span class="s2">/lib"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span>./configure<span class="w"> </span>--with-pydebug<span class="w"> </span><span class="se">\</span> <span class="w"> </span>--with-openssl<span class="o">=</span><span class="s2">"</span><span class="k">$(</span>brew<span class="w"> </span>--prefix<span class="w"> </span>openssl@3<span class="k">)</span><span class="s2">"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span>--with-tcltk-libs<span class="o">=</span><span class="s2">"</span><span class="k">$(</span>pkg-config<span class="w"> </span>--libs<span class="w"> </span>tcl<span class="w"> </span>tk<span class="k">)</span><span class="s2">"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span>--with-tcltk-includes<span class="o">=</span><span class="s2">"</span><span class="k">$(</span>pkg-config<span class="w"> </span>--cflags<span class="w"> </span>tcl<span class="w"> </span>tk<span class="k">)</span><span class="s2">"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span>--with-dbmliborder<span class="o">=</span>gdbm:ndbm </pre></div> </div> <p>(<code class="docutils literal notranslate"><span class="pre">--with-dbmliborder</span></code> is a workaround for a Homebrew-specific change to <code class="docutils literal notranslate"><span class="pre">gdbm</span></code>; see <a class="reference external" href="https://github.com/python/cpython/issues/89452">#89452</a> for details.)</p> </div> </div> </div> <input class="tab-input" id="tab-set--3-input--2" name="tab-set--3" type="radio"><label class="tab-label" for="tab-set--3-input--2">MacPorts</label><div class="tab-content docutils container"> <p>For <strong>MacPorts</strong>, install dependencies using <code class="docutils literal notranslate"><span class="pre">port</span></code>:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>sudo<span class="w"> </span>port<span class="w"> </span>install<span class="w"> </span>pkgconfig<span class="w"> </span>openssl<span class="w"> </span>xz<span class="w"> </span>gdbm<span class="w"> </span>tcl<span class="w"> </span>tk<span class="w"> </span>+quartz<span class="w"> </span>mpdecimal </pre></div> </div> <div class="tab-set docutils container"> <input checked="True" class="tab-input" id="tab-set--2-input--1" name="tab-set--2" type="radio"><label class="tab-label" for="tab-set--2-input--1">Python 3.13+</label><div class="tab-content docutils container"> <p>For Python 3.13 and newer:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nv">GDBM_CFLAGS</span><span class="o">=</span><span class="s2">"-I</span><span class="k">$(</span>dirname<span class="w"> </span><span class="k">$(</span>dirname<span class="w"> </span><span class="k">$(</span>which<span class="w"> </span>port<span class="k">)))</span><span class="s2">/include"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span><span class="nv">GDBM_LIBS</span><span class="o">=</span><span class="s2">"-L</span><span class="k">$(</span>dirname<span class="w"> </span><span class="k">$(</span>dirname<span class="w"> </span><span class="k">$(</span>which<span class="w"> </span>port<span class="k">)))</span><span class="s2">/lib -lgdbm"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span>./configure<span class="w"> </span>--with-pydebug<span class="w"> </span><span class="se">\</span> <span class="w"> </span>--with-system-libmpdec </pre></div> </div> </div> <input class="tab-input" id="tab-set--2-input--2" name="tab-set--2" type="radio"><label class="tab-label" for="tab-set--2-input--2">Python 3.11-3.12</label><div class="tab-content docutils container"> <p>For Python 3.11 and 3.12:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nv">GDBM_CFLAGS</span><span class="o">=</span><span class="s2">"-I</span><span class="k">$(</span>dirname<span class="w"> </span><span class="k">$(</span>dirname<span class="w"> </span><span class="k">$(</span>which<span class="w"> </span>port<span class="k">)))</span><span class="s2">/include"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span><span class="nv">GDBM_LIBS</span><span class="o">=</span><span class="s2">"-L</span><span class="k">$(</span>dirname<span class="w"> </span><span class="k">$(</span>dirname<span class="w"> </span><span class="k">$(</span>which<span class="w"> </span>port<span class="k">)))</span><span class="s2">/lib -lgdbm"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span>./configure<span class="w"> </span>--with-pydebug </pre></div> </div> </div> </div> </div> </div> <p>And finally, run <code class="docutils literal notranslate"><span class="pre">make</span></code>:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>make<span class="w"> </span>-s<span class="w"> </span>-j2 </pre></div> </div> <p>There will sometimes be optional modules added for a new release which won’t yet be identified in the OS-level build dependencies. In those cases, just ask for assistance in the <em>Core Development</em> category on <a class="reference internal" href="../getting-help/#help-discourse"><span class="std std-ref">Discourse</span></a>.</p> <p>Explaining how to build optional dependencies on a Unix-based system without root access is beyond the scope of this guide.</p> <p>For more details on various options and considerations for building, refer to the <a class="reference external" href="https://github.com/python/cpython/blob/main/Mac/README.rst">macOS README</a>.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>While you need a C compiler to build CPython, you don’t need any knowledge of the C language to contribute! Vast areas of CPython are written completely in Python: as of this writing, CPython contains slightly more Python code than C.</p> </div> </div> <input class="tab-input" id="tab-set--4-input--3" name="tab-set--4" type="radio"><label class="tab-label" for="tab-set--4-input--3">Windows</label><div class="tab-content docutils container"> <p>On Windows, extensions are already included and built automatically.</p> </div> <input class="tab-input" id="tab-set--4-input--4" name="tab-set--4" type="radio"><label class="tab-label" for="tab-set--4-input--4">Android</label><div class="tab-content docutils container"> <p>The BeeWare project maintains <a class="reference external" href="https://github.com/beeware/cpython-android-source-deps">scripts for building Android dependencies</a>, and distributes <a class="reference external" href="https://github.com/beeware/cpython-android-source-deps/releases">pre-compiled binaries</a> for each of them. These binaries are automatically downloaded and used by the CPython build script at <a class="extlink-cpy-file reference external" href="https://github.com/python/cpython/blob/main/Android/android.py">Android/android.py</a>.</p> </div> <input class="tab-input" id="tab-set--4-input--5" name="tab-set--4" type="radio"><label class="tab-label" for="tab-set--4-input--5">iOS</label><div class="tab-content docutils container"> <p>As with CPython itself, the dependencies for CPython must be compiled for each of the hardware architectures that iOS supports. Consult the documentation for <a class="reference external" href="https://tukaani.org/xz/">XZ</a>, <a class="reference external" href="https://sourceware.org/bzip2/">bzip2</a>, <a class="reference external" href="https://www.openssl.org">OpenSSL</a> and <a class="reference external" href="https://github.com/libffi/libffi">libffi</a> for details on how to configure the project for cross-platform iOS builds.</p> <p>Alternatively, the <a class="reference external" href="https://beeware.org">BeeWare Project</a> maintains a <a class="reference external" href="https://github.com/beeware/cpython-apple-source-deps">project for building iOS dependencies</a>, and distributes <a class="reference external" href="https://github.com/beeware/cpython-apple-source-deps/releases">pre-compiled binaries</a> for each of the dependencies. If you use this project to build the dependencies yourself, the subfolders of the <code class="docutils literal notranslate"><span class="pre">install</span></code> folder can be used to configure CPython. If you use the pre-compiled binaries, you should unpack each tarball into a separate folder, and use that folder as the configuration target.</p> </div> </div> </section> <section id="regenerate-configure"> <span id="id5"></span><h2>Regenerate <code class="docutils literal notranslate"><span class="pre">configure</span></code><a class="headerlink" href="#regenerate-configure" title="Link to this heading">¶</a></h2> <p>If a change is made to Python which relies on some POSIX system-specific functionality (such as using a new system call), it is necessary to update the <a class="extlink-cpy-file reference external" href="https://github.com/python/cpython/blob/main/configure">configure</a> script to test for availability of the functionality. Python’s <code class="file docutils literal notranslate"><span class="pre">configure</span></code> script is generated from <a class="extlink-cpy-file reference external" href="https://github.com/python/cpython/blob/main/configure.ac">configure.ac</a> using <a class="reference external" href="https://www.gnu.org/software/autoconf/">GNU Autoconf</a>.</p> <p>After editing <code class="file docutils literal notranslate"><span class="pre">configure.ac</span></code>, run <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">regen-configure</span></code> to generate <code class="file docutils literal notranslate"><span class="pre">configure</span></code>, <a class="extlink-cpy-file reference external" href="https://github.com/python/cpython/blob/main/pyconfig.h.in">pyconfig.h.in</a>, and <a class="extlink-cpy-file reference external" href="https://github.com/python/cpython/blob/main/aclocal.m4">aclocal.m4</a>. When submitting a pull request with changes made to <code class="file docutils literal notranslate"><span class="pre">configure.ac</span></code>, make sure you also commit the changes in the generated files.</p> <p>Python’s <code class="file docutils literal notranslate"><span class="pre">configure.ac</span></code> script requires a specific version of GNU Autoconf. For Python 3.12 and newer, GNU Autoconf v2.71 is required. For Python 3.11 and earlier, GNU Autoconf v2.69 is required.</p> <p>The recommended and by far the easiest way to regenerate <code class="file docutils literal notranslate"><span class="pre">configure</span></code> is:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>make<span class="w"> </span>regen-configure </pre></div> </div> <p>This will use Podman or Docker to do the regeneration with the proper version of GNU Autoconf.</p> <p>If you cannot (or don’t want to) use <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">regen-configure</span></code>, install the <strong class="program">autoconf-archive</strong> and <strong class="program">pkg-config</strong> utilities, and make sure the <code class="file docutils literal notranslate"><span class="pre">pkg.m4</span></code> macro file located in the appropriate <strong class="program">aclocal</strong> location:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ls<span class="w"> </span><span class="k">$(</span>aclocal<span class="w"> </span>--print-ac-dir<span class="k">)</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>grep<span class="w"> </span>pkg.m4 </pre></div> </div> <div class="admonition note"> <p class="admonition-title">Note</p> <p>Running <strong class="program">autoreconf</strong> is not the same as running <strong class="program">autoconf</strong>. For example, running <strong class="program">autoconf</strong> by itself will not regenerate <code class="file docutils literal notranslate"><span class="pre">pyconfig.h.in</span></code>. <strong class="program">autoreconf</strong> runs <strong class="program">autoconf</strong> and a number of other tools repeatedly as appropriate.</p> </div> </section> <section id="regenerate-the-abi-dump"> <h2>Regenerate the ABI dump<a class="headerlink" href="#regenerate-the-abi-dump" title="Link to this heading">¶</a></h2> <p>Maintenance branches (not <code class="docutils literal notranslate"><span class="pre">main</span></code>) have a special file located in <code class="docutils literal notranslate"><span class="pre">Doc/data/pythonX.Y.abi</span></code> that allows us to know if a given pull request affects the public ABI. This file is used by the GitHub CI in a check called <code class="docutils literal notranslate"><span class="pre">Check</span> <span class="pre">if</span> <span class="pre">the</span> <span class="pre">ABI</span> <span class="pre">has</span> <span class="pre">changed</span></code> that will fail if a given pull request has changes to the ABI and the ABI file is not updated.</p> <p>This check acts as a fail-safe and <strong>doesn’t necessarily mean that the pull request cannot be merged</strong>. When this check fails you should add the relevant release manager to the PR so that they are aware of the change and they can validate if the change can be made or not.</p> <div class="admonition important"> <p class="admonition-title">Important</p> <p>ABI changes are allowed before the first release candidate. After the first release candidate, all further releases must have the same ABI for ensuring compatibility with native extensions and other tools that interact with the Python interpreter. See the documentation about the <a class="reference internal" href="../../developer-workflow/development-cycle/#rc"><span class="std std-ref">release candidate</span></a> phase.</p> </div> <p>When the PR check fails, the associated run will have the updated ABI file attached as an artifact. After release manager approval, you can download and add this file into your PR to pass the check.</p> <p>You can regenerate the ABI file by yourself by invoking the <code class="docutils literal notranslate"><span class="pre">regen</span> <span class="pre">abidump</span></code> Make target. Note that for doing this you need to regenerate the ABI file in the same environment that the GitHub CI uses to check for it. This is because different platforms may include some platform-specific details that make the check fail even if the Python ABI is the same. The easier way to regenerate the ABI file using the same platform as the CI uses is by using Docker:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp"># </span>In<span class="w"> </span>the<span class="w"> </span>CPython<span class="w"> </span>root: <span class="gp">$ </span>docker<span class="w"> </span>run<span class="w"> </span>-v<span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span>:/src:Z<span class="w"> </span>-w<span class="w"> </span>/src<span class="w"> </span>--rm<span class="w"> </span>-it<span class="w"> </span>ubuntu:22.04<span class="w"> </span><span class="se">\</span> <span class="w"> </span>bash<span class="w"> </span>/src/.github/workflows/regen-abidump.sh </pre></div> </div> <p>Note that the <code class="docutils literal notranslate"><span class="pre">ubuntu</span></code> version used to execute the script matters and <strong>must</strong> match the version used by the CI to check the ABI. See the <code class="docutils literal notranslate"><span class="pre">.github/workflows/build.yml</span></code> file for more information.</p> </section> <section id="troubleshoot-the-build"> <span id="build-troubleshooting"></span><h2>Troubleshoot the build<a class="headerlink" href="#troubleshoot-the-build" title="Link to this heading">¶</a></h2> <p>This section lists some of the common problems that may arise during the compilation of Python, with proposed solutions.</p> <section id="avoid-recreating-auto-generated-files"> <h3>Avoid recreating auto-generated files<a class="headerlink" href="#avoid-recreating-auto-generated-files" title="Link to this heading">¶</a></h3> <p>Under some circumstances you may encounter Python errors in scripts like <code class="docutils literal notranslate"><span class="pre">Parser/asdl_c.py</span></code> or <code class="docutils literal notranslate"><span class="pre">Python/makeopcodetargets.py</span></code> while running <code class="docutils literal notranslate"><span class="pre">make</span></code>. Python auto-generates some of its own code, and a full build from scratch needs to run the auto-generation scripts. However, this makes the Python build require an already installed Python interpreter; this can also cause version mismatches when trying to build an old (2.x) Python with a new (3.x) Python installed, or vice versa.</p> <p>To overcome this problem, auto-generated files are also checked into the Git repository. So if you don’t touch the auto-generation scripts, there’s no real need to auto-generate anything.</p> </section> </section> <section id="editors-and-tools"> <h2>Editors and tools<a class="headerlink" href="#editors-and-tools" title="Link to this heading">¶</a></h2> <p>Python is used widely enough that practically all code editors have some form of support for writing Python code. Various coding tools also include Python support.</p> <p>For editors and tools which the core developers have felt some special comment is needed for coding <em>in</em> Python, see <a class="reference internal" href="../../#resources"><span class="std std-ref">Additional resources</span></a>.</p> </section> <section id="directory-structure"> <span id="build-directory-structure"></span><h2>Directory structure<a class="headerlink" href="#directory-structure" title="Link to this heading">¶</a></h2> <p>There are several top-level directories in the CPython source tree. Knowing what each one is meant to hold will help you find where a certain piece of functionality is implemented. Do realize, though, there are always exceptions to every rule.</p> <dl class="simple"> <dt><code class="docutils literal notranslate"><span class="pre">Doc</span></code></dt><dd><p>The official documentation. This is what <a class="reference external" href="https://docs.python.org/">https://docs.python.org/</a> uses. See also <a class="reference internal" href="../../documentation/start-documenting/#building-doc"><span class="std std-ref">Building the documentation</span></a>.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">Grammar</span></code></dt><dd><p>Contains the <abbr title="Extended Backus-Naur Form">EBNF</abbr> grammar file for Python.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">Include</span></code></dt><dd><p>Contains all interpreter-wide header files.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">Lib</span></code></dt><dd><p>The part of the standard library implemented in pure Python.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">Mac</span></code></dt><dd><p>Mac-specific code (for example, using IDLE as a macOS application).</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">Misc</span></code></dt><dd><p>Things that do not belong elsewhere. Typically this is varying kinds of developer-specific documentation.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">Modules</span></code></dt><dd><p>The part of the standard library (plus some other code) that is implemented in C.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">Objects</span></code></dt><dd><p>Code for all built-in types.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">PC</span></code></dt><dd><p>Windows-specific code.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">PCbuild</span></code></dt><dd><p>Build files for the version of MSVC currently used for the Windows installers provided on python.org.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">Parser</span></code></dt><dd><p>Code related to the parser. The definition of the AST nodes is also kept here.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">Programs</span></code></dt><dd><p>Source code for C executables, including the main function for the CPython interpreter.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">Python</span></code></dt><dd><p>The code that makes up the core CPython runtime. This includes the compiler, eval loop and various built-in modules.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">Tools</span></code></dt><dd><p>Various tools that are (or have been) used to maintain Python.</p> </dd> </dl> </section> <section id="contribute-using-github-codespaces"> <span id="using-codespaces"></span><h2>Contribute using GitHub Codespaces<a class="headerlink" href="#contribute-using-github-codespaces" title="Link to this heading">¶</a></h2> <section id="what-is-github-codespaces"> <span id="codespaces-whats-codespaces"></span><h3>What is GitHub Codespaces?<a class="headerlink" href="#what-is-github-codespaces" title="Link to this heading">¶</a></h3> <p>If you’d like to start contributing to CPython without needing to set up a local developer environment, you can use <a class="reference external" href="https://github.com/features/codespaces">GitHub Codespaces</a>. Codespaces is a cloud-based development environment offered by GitHub that allows developers to write, build, test, and debug code directly within their web browser or in Visual Studio Code (VS Code).</p> <p>To help you get started, CPython contains a <a class="reference external" href="https://github.com/python/cpython/tree/main/.devcontainer">devcontainer folder</a> with a JSON configuration file that provides consistent and versioned codespace configurations for all users of the project. It also contains a Dockerfile that allows you to set up the same environment but locally in a Docker container if you’d prefer to use that directly.</p> </section> <section id="create-a-cpython-codespace"> <span id="codespaces-create-a-codespace"></span><h3>Create a CPython codespace<a class="headerlink" href="#create-a-cpython-codespace" title="Link to this heading">¶</a></h3> <p>Here are the basic steps needed to contribute a pull request using Codespaces. You first need to navigate to the <a class="reference external" href="https://github.com/python/cpython">CPython repo</a> hosted on GitHub.</p> <p>Then you will need to:</p> <ol class="arabic simple"> <li><p>Press the <code class="docutils literal notranslate"><span class="pre">,</span></code> key to launch the codespace setup screen for the current branch (alternatively, click the green <span class="guilabel">Code</span> button and choose the <code class="docutils literal notranslate"><span class="pre">codespaces</span></code> tab and then press the green <span class="guilabel">Create codespace on main</span> button).</p></li> <li><p>A screen should appear that lets you know your codespace is being set up. (Note: Since the CPython devcontainer is provided, codespaces will use the configuration it specifies.)</p></li> <li><p>A <a class="reference external" href="https://vscode.dev/">web version of VS Code</a> will open inside your web browser, already linked up with your code and a terminal to the remote codespace where CPython and its documentation have already been built.</p></li> <li><p>Use the terminal with the usual Git commands to create a new branch, commit and push your changes once you’re ready!</p></li> </ol> <p>If you close your repository and come back later you can always resume your codespace by navigating to the CPython repo, selecting the codespaces tab and selecting your most recent codespaces session. You should then be able to pick up from where you left off!</p> </section> <section id="use-codespaces-locally"> <span id="codespaces-use-locally"></span><h3>Use Codespaces locally<a class="headerlink" href="#use-codespaces-locally" title="Link to this heading">¶</a></h3> <p>On the bottom left side of the codespace screen you will see a green or grey square that says <span class="guilabel">Codespaces</span>. You can click this for additional options. If you prefer working in a locally installed copy of VS Code you can select the option <code class="docutils literal notranslate"><span class="pre">Open</span> <span class="pre">in</span> <span class="pre">VS</span> <span class="pre">Code</span></code>. You will still be working on the remote codespace instance, thus using the remote instance’s compute power. The compute power may be a much higher spec than your local machine which can be helpful.</p> </section> </section> </section> </article> </div> <footer> <div class="related-pages"> <a class="next-page" href="../fixing-issues/"> <div class="page-info"> <div class="context"> <span>Next</span> </div> <div class="title">Fixing “easy” issues (and beyond)</div> </div> <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> </a> <a class="prev-page" href="../"> <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> <div class="page-info"> <div class="context"> <span>Previous</span> </div> <div class="title">Getting started</div> </div> </a> </div> <div class="bottom-of-page"> <div class="left-details"> <div class="copyright"> Copyright © 2011 Python Software Foundation </div> Made with <a href="https://www.sphinx-doc.org/">Sphinx</a> and <a class="muted-link" href="https://pradyunsg.me">@pradyunsg</a>'s <a href="https://github.com/pradyunsg/furo">Furo</a> </div> <div class="right-details"> </div> </div> </footer> </div> <aside class="toc-drawer"> <div class="toc-sticky toc-scroll"> <div class="toc-title-container"> <span class="toc-title"> On this page </span> </div> <div class="toc-tree-container"> <div class="toc-tree"> <ul> <li><a class="reference internal" href="#">Setup and building</a><ul> <li><a class="reference internal" href="#install-git">Install Git</a></li> <li><a class="reference internal" href="#get-the-source-code">Get the source code</a><ul> <li><a class="reference internal" href="#install-pre-commit-as-a-git-hook">Install pre-commit as a Git hook</a></li> </ul> </li> <li><a class="reference internal" href="#compile-and-build">Compile and build</a><ul> <li><a class="reference internal" href="#unix">Unix</a><ul> <li><a class="reference internal" href="#clang">Clang</a></li> <li><a class="reference internal" href="#optimization">Optimization</a></li> </ul> </li> <li><a class="reference internal" href="#windows">Windows</a></li> <li><a class="reference internal" href="#wasi">WASI</a></li> <li><a class="reference internal" href="#emscripten">Emscripten</a></li> <li><a class="reference internal" href="#android">Android</a></li> <li><a class="reference internal" href="#ios">iOS</a></li> </ul> </li> <li><a class="reference internal" href="#install-dependencies">Install dependencies</a></li> <li><a class="reference internal" href="#regenerate-configure">Regenerate <code class="docutils literal notranslate"><span class="pre">configure</span></code></a></li> <li><a class="reference internal" href="#regenerate-the-abi-dump">Regenerate the ABI dump</a></li> <li><a class="reference internal" href="#troubleshoot-the-build">Troubleshoot the build</a><ul> <li><a class="reference internal" href="#avoid-recreating-auto-generated-files">Avoid recreating auto-generated files</a></li> </ul> </li> <li><a class="reference internal" href="#editors-and-tools">Editors and tools</a></li> <li><a class="reference internal" href="#directory-structure">Directory structure</a></li> <li><a class="reference internal" href="#contribute-using-github-codespaces">Contribute using GitHub Codespaces</a><ul> <li><a class="reference internal" href="#what-is-github-codespaces">What is GitHub Codespaces?</a></li> <li><a class="reference internal" href="#create-a-cpython-codespace">Create a CPython codespace</a></li> <li><a class="reference internal" href="#use-codespaces-locally">Use Codespaces locally</a></li> </ul> </li> </ul> </li> </ul> </div> </div> </div> </aside> </div> </div><script src="../../_static/documentation_options.js?v=187304be"></script> <script src="../../_static/doctools.js?v=9bcbadda"></script> <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script> <script src="../../_static/scripts/furo.js?v=5fa4622c"></script> <script src="../../_static/clipboard.min.js?v=a7894cd8"></script> <script src="../../_static/copybutton.js?v=c136e461"></script> <script src="../../_static/tabs.js?v=3ee01567"></script> <script src="../../_static/activate_tab.js?v=3ac9c400"></script> </body> </html>