bunny-lab/Borealis
bunny-lab/Borealis
2
0
Fork 0
Code Issues 10 Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Borealis/Dependencies/Python/Doc/html/using/mac.html

741 lines
50 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta property="og:title" content="5. Using Python on macOS" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://docs.python.org/3/using/mac.html" />
<meta property="og:site_name" content="Python documentation" />
<meta property="og:description" content="This document aims to give an overview of macOS-specific behavior you should know about to get started with Python on Mac computers. Python on a Mac running macOS is very similar to Python on other..." />
<meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />
<meta property="og:image:alt" content="Python documentation" />
<meta name="description" content="This document aims to give an overview of macOS-specific behavior you should know about to get started with Python on Mac computers. Python on a Mac running macOS is very similar to Python on other..." />
<meta property="og:image:width" content="200">
<meta property="og:image:height" content="200">
<meta name="theme-color" content="#3776ab">
<title>5. Using Python on macOS &#8212; Python 3.13.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=23252803" />
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />
<script src="../_static/documentation_options.js?v=5d57ca2d"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.13.3 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="6. Using Python on Android" href="android.html" />
<link rel="prev" title="4. Using Python on Windows" href="windows.html" />
<link rel="canonical" href="https://docs.python.org/3/using/mac.html">
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
<link rel="shortcut icon" type="image/png" href="../_static/py.svg" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/menu.js"></script>
<script type="text/javascript" src="../_static/search-focus.js"></script>
<script type="text/javascript" src="../_static/themetoggle.js"></script>
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
<meta name="readthedocs-addons-api-version" content="1">
</head>
<body>
<div class="mobile-nav">
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
<nav class="nav-content" role="navigation">
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<span class="nav-items-wrapper">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Python logo"/>
</a>
<span class="version_switcher_placeholder"></span>
<form role="search" class="search" action="../search.html" method="get">
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
<path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
</svg>
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />
<input type="submit" value="Go"/>
</form>
</span>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label>
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">5. Using Python on macOS</a><ul>
<li><a class="reference internal" href="#using-python-for-macos-from-python-org">5.1. Using Python for macOS from <code class="docutils literal notranslate"><span class="pre">python.org</span></code></a><ul>
<li><a class="reference internal" href="#installation-steps">5.1.1. Installation steps</a></li>
<li><a class="reference internal" href="#how-to-run-a-python-script">5.1.2. How to run a Python script</a></li>
</ul>
</li>
<li><a class="reference internal" href="#alternative-distributions">5.2. Alternative Distributions</a></li>
<li><a class="reference internal" href="#installing-additional-python-packages">5.3. Installing Additional Python Packages</a></li>
<li><a class="reference internal" href="#gui-programming">5.4. GUI Programming</a></li>
<li><a class="reference internal" href="#advanced-topics">5.5. Advanced Topics</a><ul>
<li><a class="reference internal" href="#installing-free-threaded-binaries">5.5.1. Installing Free-threaded Binaries</a></li>
<li><a class="reference internal" href="#installing-using-the-command-line">5.5.2. Installing using the command line</a></li>
<li><a class="reference internal" href="#distributing-python-applications">5.5.3. Distributing Python Applications</a></li>
<li><a class="reference internal" href="#app-store-compliance">5.5.4. App Store Compliance</a></li>
</ul>
</li>
<li><a class="reference internal" href="#other-resources">5.6. Other Resources</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="windows.html"
title="previous chapter"><span class="section-number">4. </span>Using Python on Windows</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="android.html"
title="next chapter"><span class="section-number">6. </span>Using Python on Android</a></p>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a Bug</a></li>
<li>
<a href="https://github.com/python/cpython/blob/main/Doc/using/mac.rst"
rel="nofollow">Show Source
</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="android.html" title="6. Using Python on Android"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="windows.html" title="4. Using Python on Windows"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.13.3 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python Setup and Usage</a> &#187;</li>
<li class="nav-item nav-item-this"><a href=""><span class="section-number">5. </span>Using Python on macOS</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />
<input type="submit" value="Go" />
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="using-python-on-macos">
<span id="using-on-mac"></span><h1><span class="section-number">5. </span>Using Python on macOS<a class="headerlink" href="#using-python-on-macos" title="Link to this heading"></a></h1>
<p>This document aims to give an overview of macOS-specific behavior you should
know about to get started with Python on Mac computers.
Python on a Mac running macOS is very similar to Python on other Unix-derived platforms,
but there are some differences in installation and some features.</p>
<p>There are various ways to obtain and install Python for macOS.
Pre-built versions of the most recent versions of Python are available
from a number of distributors. Much of this document describes use of
the Pythons provided by the CPython release team for download from
the <a class="reference external" href="https://www.python.org/downloads/">python.org website</a>. See
<a class="reference internal" href="#alternative-bundles"><span class="std std-ref">Alternative Distributions</span></a> for some other options.</p>
<section id="using-python-for-macos-from-python-org">
<span id="getting-and-installing-macpython"></span><span id="getting-osx"></span><h2><span class="section-number">5.1. </span>Using Python for macOS from <code class="docutils literal notranslate"><span class="pre">python.org</span></code><a class="headerlink" href="#using-python-for-macos-from-python-org" title="Link to this heading"></a></h2>
<section id="installation-steps">
<h3><span class="section-number">5.1.1. </span>Installation steps<a class="headerlink" href="#installation-steps" title="Link to this heading"></a></h3>
<p>For <a class="reference external" href="https://www.python.org/downloads/">current Python versions</a>
(other than those in <code class="docutils literal notranslate"><span class="pre">security</span></code> status), the release team produces a
<strong>Python for macOS</strong> installer package for each new release.
A list of available installers
is available <a class="reference external" href="https://www.python.org/downloads/macos/">here</a>.
We recommend using the most recent supported Python version where possible.
Current installers provide a
<a class="reference external" href="https://en.wikipedia.org/wiki/Universal_binary">universal2 binary</a> build
of Python which runs natively on all Macs (Apple Silicon and Intel) that are
supported by a wide range of macOS versions,
currently typically from at least <strong>macOS 10.13 High Sierra</strong> on.</p>
<p>The downloaded file is a standard macOS installer package file (<code class="docutils literal notranslate"><span class="pre">.pkg</span></code>).
File integrity information (checksum, size, sigstore signature, etc) for each file is included
on the release download page. Installer packages and their contents are signed and notarized
with <code class="docutils literal notranslate"><span class="pre">Python</span> <span class="pre">Software</span> <span class="pre">Foundation</span></code> Apple Developer ID certificates
to meet <a class="reference external" href="https://support.apple.com/en-us/102445">macOS Gatekeeper requirements</a>.</p>
<p>For a default installation, double-click on the downloaded installer package file.
This should launch the standard macOS Installer app and display the first of several
installer windows steps.</p>
<img alt="../_images/mac_installer_01_introduction.png" src="../_images/mac_installer_01_introduction.png" />
<p>Clicking on the <strong>Continue</strong> button brings up the <strong>Read Me</strong> for this installer.
Besides other important information, the <strong>Read Me</strong> documents which Python version is
going to be installed and on what versions of macOS it is supported. You may need
to scroll through to read the whole file. By default, this <strong>Read Me</strong> will also be
installed in <code class="docutils literal notranslate"><span class="pre">/Applications/Python</span> <span class="pre">3.13/</span></code> and available to read anytime.</p>
<img alt="../_images/mac_installer_02_readme.png" src="../_images/mac_installer_02_readme.png" />
<p>Clicking on <strong>Continue</strong> proceeds to display the license for Python and for
other included software. You will then need to <strong>Agree</strong> to the license terms
before proceeding to the next step. This license file will also be installed
and available to be read later.</p>
<img alt="../_images/mac_installer_03_license.png" src="../_images/mac_installer_03_license.png" />
<p>After the license terms are accepted, the next step is the <strong>Installation Type</strong>
display. For most uses, the standard set of installation operations is appropriate.</p>
<img alt="../_images/mac_installer_04_installation_type.png" src="../_images/mac_installer_04_installation_type.png" />
<p>By pressing the <strong>Customize</strong> button, you can choose to omit or select certain package
components of the installer. Click on each package name to see a description of
what it installs.
To also install support for the optional experimental free-threaded feature,
see <a class="reference internal" href="#install-freethreaded-macos"><span class="std std-ref">Installing Free-threaded Binaries</span></a>.</p>
<img alt="../_images/mac_installer_05_custom_install.png" src="../_images/mac_installer_05_custom_install.png" />
<p>In either case, clicking <strong>Install</strong> will begin the install process by asking
permission to install new software. A macOS user name with <code class="docutils literal notranslate"><span class="pre">Administrator</span></code> privilege
is needed as the installed Python will be available to all users of the Mac.</p>
<p>When the installation is complete, the <strong>Summary</strong> window will appear.</p>
<img alt="../_images/mac_installer_06_summary.png" src="../_images/mac_installer_06_summary.png" />
<p>Double-click on the <strong class="command">Install Certificates.command</strong>
icon or file in the <code class="docutils literal notranslate"><span class="pre">/Applications/Python</span> <span class="pre">3.13/</span></code> window to complete the
installation.</p>
<img alt="../_images/mac_installer_07_applications.png" src="../_images/mac_installer_07_applications.png" />
<p>This will open a temporary <strong class="program">Terminal</strong> shell window that
will use the new Python to download and install SSL root certificates
for its use.</p>
<img alt="../_images/mac_installer_08_install_certificates.png" src="../_images/mac_installer_08_install_certificates.png" />
<p>If <code class="docutils literal notranslate"><span class="pre">Successfully</span> <span class="pre">installed</span> <span class="pre">certifi</span></code> and <code class="docutils literal notranslate"><span class="pre">update</span> <span class="pre">complete</span></code> appears
in the terminal window, the installation is complete.
Close this terminal window and the installer window.</p>
<p>A default install will include:</p>
<ul class="simple">
<li><p>A <code class="docutils literal notranslate"><span class="pre">Python</span> <span class="pre">3.13</span></code> folder in your <code class="file docutils literal notranslate"><span class="pre">Applications</span></code> folder. In here
you find <strong class="program">IDLE</strong>, the development environment that is a standard part of official
Python distributions; and <strong class="program">Python Launcher</strong>, which handles double-clicking Python
scripts from the macOS <a class="reference external" href="https://support.apple.com/en-us/HT201732">Finder</a>.</p></li>
<li><p>A framework <code class="file docutils literal notranslate"><span class="pre">/Library/Frameworks/Python.framework</span></code>, which includes the
Python executable and libraries. The installer adds this location to your shell
path. To uninstall Python, you can remove these three things.
Symlinks to the Python executable are placed in <code class="file docutils literal notranslate"><span class="pre">/usr/local/bin/</span></code>.</p></li>
</ul>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Recent versions of macOS include a <strong class="command">python3</strong> command in <code class="file docutils literal notranslate"><span class="pre">/usr/bin/python3</span></code>
that links to a usually older and incomplete version of Python provided by and for use by
the Apple development tools, <strong class="program">Xcode</strong> or the <strong class="program">Command Line Tools for Xcode</strong>.
You should never modify or attempt to delete this installation, as it is
Apple-controlled and is used by Apple-provided or third-party software. If
you choose to install a newer Python version from <code class="docutils literal notranslate"><span class="pre">python.org</span></code>, you will have
two different but functional Python installations on your computer that
can co-exist. The default installer options should ensure that its <strong class="command">python3</strong>
will be used instead of the system <strong class="command">python3</strong>.</p>
</div>
</section>
<section id="how-to-run-a-python-script">
<h3><span class="section-number">5.1.2. </span>How to run a Python script<a class="headerlink" href="#how-to-run-a-python-script" title="Link to this heading"></a></h3>
<p>There are two ways to invoke the Python interpreter.
If you are familiar with using a Unix shell in a terminal
window, you can invoke <code class="docutils literal notranslate"><span class="pre">python3.13</span></code> or <code class="docutils literal notranslate"><span class="pre">python3</span></code> optionally
followed by one or more command line options (described in <a class="reference internal" href="cmdline.html#using-on-general"><span class="std std-ref">Command line and environment</span></a>).
The Python tutorial also has a useful section on
<a class="reference internal" href="../tutorial/appendix.html#tut-interac"><span class="std std-ref">using Python interactively from a shell</span></a>.</p>
<p>You can also invoke the interpreter through an integrated
development environment.
<a class="reference internal" href="../library/idle.html#idle"><span class="std std-ref">IDLE — Python editor and shell</span></a> is a basic editor and interpreter environment
which is included with the standard distribution of Python.
<strong class="program">IDLE</strong> includes a Help menu that allows you to access Python documentation. If you
are completely new to Python, you can read the tutorial introduction
in that document.</p>
<p>There are many other editors and IDEs available, see <a class="reference internal" href="editors.html#editors"><span class="std std-ref">Editors and IDEs</span></a>
for more information.</p>
<p>To run a Python script file from the terminal window, you can
invoke the interpreter with the name of the script file:</p>
<blockquote>
<div><p><code class="docutils literal notranslate"><span class="pre">python3.13</span></code> <code class="docutils literal notranslate"><span class="pre">myscript.py</span></code></p>
</div></blockquote>
<p>To run your script from the Finder, you can either:</p>
<ul class="simple">
<li><p>Drag it to <strong class="program">Python Launcher</strong>.</p></li>
<li><p>Select <strong class="program">Python Launcher</strong> as the default application to open your
script (or any <code class="docutils literal notranslate"><span class="pre">.py</span></code> script) through the Finder Info window and double-click it.
<strong class="program">Python Launcher</strong> has various preferences to control how your script is
launched. Option-dragging allows you to change these for one invocation, or use
its <code class="docutils literal notranslate"><span class="pre">Preferences</span></code> menu to change things globally.</p></li>
</ul>
<p>Be aware that running the script directly from the macOS Finder might
produce different results than when running from a terminal window as
the script will not be run in the usual shell environment including
any setting of environment variables in shell profiles.
And, as with any other script or program,
be certain of what you are about to run.</p>
</section>
</section>
<section id="alternative-distributions">
<span id="alternative-bundles"></span><h2><span class="section-number">5.2. </span>Alternative Distributions<a class="headerlink" href="#alternative-distributions" title="Link to this heading"></a></h2>
<p>Besides the standard <code class="docutils literal notranslate"><span class="pre">python.org</span></code> for macOS installer, there are third-party
distributions for macOS that may include additional functionality.
Some popular distributions and their key features:</p>
<dl class="simple">
<dt><a class="reference external" href="https://www.activestate.com/products/python/">ActivePython</a></dt><dd><p>Installer with multi-platform compatibility, documentation</p>
</dd>
<dt><a class="reference external" href="https://www.anaconda.com/download/">Anaconda</a></dt><dd><p>Popular scientific modules (such as numpy, scipy, and pandas) and the
<code class="docutils literal notranslate"><span class="pre">conda</span></code> package manager.</p>
</dd>
<dt><a class="reference external" href="https://brew.sh">Homebrew</a></dt><dd><p>Package manager for macOS including multiple versions of Python and many
third-party Python-based packages (including numpy, scipy, and pandas).</p>
</dd>
<dt><a class="reference external" href="https://www.macports.org">MacPorts</a></dt><dd><p>Another package manager for macOS including multiple versions of Python and many
third-party Python-based packages. May include pre-built versions of Python and
many packages for older versions of macOS.</p>
</dd>
</dl>
<p>Note that distributions might not include the latest versions of Python or
other libraries, and are not maintained or supported by the core Python team.</p>
</section>
<section id="installing-additional-python-packages">
<span id="mac-package-manager"></span><h2><span class="section-number">5.3. </span>Installing Additional Python Packages<a class="headerlink" href="#installing-additional-python-packages" title="Link to this heading"></a></h2>
<p>Refer to the <a class="reference external" href="https://packaging.python.org/en/latest/tutorials/installing-packages/">Python Packaging User Guide</a> for more information.</p>
</section>
<section id="gui-programming">
<span id="gui-programming-on-the-mac"></span><span id="osx-gui-scripts"></span><h2><span class="section-number">5.4. </span>GUI Programming<a class="headerlink" href="#gui-programming" title="Link to this heading"></a></h2>
<p>There are several options for building GUI applications on the Mac with Python.</p>
<p>The standard Python GUI toolkit is <a class="reference internal" href="../library/tkinter.html#module-tkinter" title="tkinter: Interface to Tcl/Tk for graphical user interfaces"><code class="xref py py-mod docutils literal notranslate"><span class="pre">tkinter</span></code></a>, based on the cross-platform
Tk toolkit (<a class="reference external" href="https://www.tcl.tk">https://www.tcl.tk</a>). A macOS-native version of Tk is included with
the installer.</p>
<p><em>PyObjC</em> is a Python binding to Apple’s Objective-C/Cocoa framework.
Information on PyObjC is available from <a class="extlink-pypi reference external" href="https://pypi.org/project/pyobjc/">pyobjc</a>.</p>
<p>A number of alternative macOS GUI toolkits are available including:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://www.qt.io/qt-for-python">PySide</a>: Official Python bindings to the
<a class="reference external" href="https://wiki.qt.io/Qt_for_Python">Qt GUI toolkit</a>.</p></li>
<li><p><a class="reference external" href="https://riverbankcomputing.com/software/pyqt/">PyQt</a>: Alternative
Python bindings to Qt.</p></li>
<li><p><a class="reference external" href="https://kivy.org">Kivy</a>: A cross-platform GUI toolkit that supports
desktop and mobile platforms.</p></li>
<li><p><a class="reference external" href="https://toga.readthedocs.io">Toga</a>: Part of the <a class="reference external" href="https://beeware.org">BeeWare Project</a>; supports desktop, mobile, web and console apps.</p></li>
<li><p><a class="reference external" href="https://wxpython.org">wxPython</a>: A cross-platform toolkit that
supports desktop operating systems.</p></li>
</ul>
</section>
<section id="advanced-topics">
<h2><span class="section-number">5.5. </span>Advanced Topics<a class="headerlink" href="#advanced-topics" title="Link to this heading"></a></h2>
<section id="installing-free-threaded-binaries">
<span id="install-freethreaded-macos"></span><h3><span class="section-number">5.5.1. </span>Installing Free-threaded Binaries<a class="headerlink" href="#installing-free-threaded-binaries" title="Link to this heading"></a></h3>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.13: </span>(Experimental)</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Everything described in this section is considered experimental,
and should be expected to change in future releases.</p>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">python.org</span></code> <a class="reference internal" href="#getting-and-installing-macpython"><span class="std std-ref">Python for macOS</span></a>
installer package can optionally install an additional build of
Python 3.13 that supports <span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0703/"><strong>PEP 703</strong></a>, the experimental free-threading feature
(running with the <a class="reference internal" href="../glossary.html#term-global-interpreter-lock"><span class="xref std std-term">global interpreter lock</span></a> disabled).
Check the release page on <code class="docutils literal notranslate"><span class="pre">python.org</span></code> for possible updated information.</p>
<p>Because this feature is still considered experimental, the support for it
is not installed by default. It is packaged as a separate install option,
available by clicking the <strong>Customize</strong> button on the <strong>Installation Type</strong>
step of the installer as described above.</p>
<img alt="../_images/mac_installer_09_custom_install_free_threaded.png" src="../_images/mac_installer_09_custom_install_free_threaded.png" />
<p>If the box next to the <strong>Free-threaded Python</strong> package name is checked,
a separate <code class="file docutils literal notranslate"><span class="pre">PythonT.framework</span></code> will also be installed
alongside the normal <code class="file docutils literal notranslate"><span class="pre">Python.framework</span></code> in <code class="file docutils literal notranslate"><span class="pre">/Library/Frameworks</span></code>.
This configuration allows a free-threaded Python 3.13 build to co-exist
on your system with a traditional (GIL only) Python 3.13 build with
minimal risk while installing or testing. This installation layout is itself
experimental and is subject to change in future releases.</p>
<p>Known cautions and limitations:</p>
<ul>
<li><p>The <strong>UNIX command-line tools</strong> package, which is selected by default,
will install links in <code class="file docutils literal notranslate"><span class="pre">/usr/local/bin</span></code> for <code class="docutils literal notranslate"><span class="pre">python3.13t</span></code>,
the free-threaded interpreter, and <code class="docutils literal notranslate"><span class="pre">python3.13t-config</span></code>,
a configuration utility which may be useful for package builders.
Since <code class="file docutils literal notranslate"><span class="pre">/usr/local/bin</span></code> is typically included in your shell <code class="docutils literal notranslate"><span class="pre">PATH</span></code>,
in most cases no changes to your <code class="docutils literal notranslate"><span class="pre">PATH</span></code> environment variables should
be needed to use <code class="docutils literal notranslate"><span class="pre">python3.13t</span></code>.</p></li>
<li><p>For this release, the <strong>Shell profile updater</strong> package and the
<code class="file docutils literal notranslate"><span class="pre">Update</span> <span class="pre">Shell</span> <span class="pre">Profile.command</span></code> in <code class="docutils literal notranslate"><span class="pre">/Applications/Python</span> <span class="pre">3.13/</span></code>
do not support the free-threaded package.</p></li>
<li><p>The free-threaded build and the traditional build have separate search
paths and separate <code class="file docutils literal notranslate"><span class="pre">site-packages</span></code> directories so, by default,
if you need a package available in both builds, it may need to be installed in both.
The free-threaded package will install a separate instance of <strong class="program">pip</strong> for use
with <code class="docutils literal notranslate"><span class="pre">python3.13t</span></code>.</p>
<ul>
<li><p>To install a package using <strong class="command">pip</strong> without a <strong class="command">venv</strong>:</p>
<blockquote>
<div><p><code class="docutils literal notranslate"><span class="pre">python3.13t</span></code> <code class="docutils literal notranslate"><span class="pre">-m</span> <span class="pre">pip</span> <span class="pre">install</span> <span class="pre">&lt;package_name&gt;</span></code></p>
</div></blockquote>
</li>
</ul>
</li>
<li><p>When working with multiple Python environments, it is usually safest and easiest
to <a class="reference internal" href="../tutorial/venv.html#tut-venv"><span class="std std-ref">create and use virtual environments</span></a>.
This can avoid possible command name conflicts and confusion about which Python is in use:</p>
<blockquote>
<div><p><code class="docutils literal notranslate"><span class="pre">python3.13t</span></code> <code class="docutils literal notranslate"><span class="pre">-m</span> <span class="pre">venv</span> <span class="pre">&lt;venv_name&gt;</span></code></p>
</div></blockquote>
<p>then <strong class="command">activate</strong>.</p>
</li>
<li><p>To run a free-threaded version of IDLE:</p>
<blockquote>
<div><p><code class="docutils literal notranslate"><span class="pre">python3.13t</span></code> <code class="docutils literal notranslate"><span class="pre">-m</span> <span class="pre">idlelib</span></code></p>
</div></blockquote>
</li>
<li><p>The interpreters in both builds respond to the same
<a class="reference internal" href="cmdline.html#using-on-envvars"><span class="std std-ref">PYTHON environment variables</span></a>
which may have unexpected results, for example, if you have <code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code>
set in a shell profile. If necessary, there are
<a class="reference internal" href="cmdline.html#using-on-interface-options"><span class="std std-ref">command line options</span></a> like <code class="docutils literal notranslate"><span class="pre">-E</span></code>
to ignore these environment variables.</p></li>
<li><p>The free-threaded build links to the third-party shared libraries,
such as <code class="docutils literal notranslate"><span class="pre">OpenSSL</span></code> and <code class="docutils literal notranslate"><span class="pre">Tk</span></code>, installed in the traditional framework.
This means that both builds also share one set of trust certificates
as installed by the <strong class="command">Install Certificates.command</strong> script,
thus it only needs to be run once.</p></li>
<li><p>If you cannot depend on the link in <code class="docutils literal notranslate"><span class="pre">/usr/local/bin</span></code> pointing to the
<code class="docutils literal notranslate"><span class="pre">python.org</span></code> free-threaded <code class="docutils literal notranslate"><span class="pre">python3.13t</span></code> (for example, if you want
to install your own version there or some other distribution does),
you can explicitly set your shell <code class="docutils literal notranslate"><span class="pre">PATH</span></code> environment variable to
include the <code class="docutils literal notranslate"><span class="pre">PythonT</span></code> framework <code class="docutils literal notranslate"><span class="pre">bin</span></code> directory:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="nb">export</span><span class="w"> </span><span class="nv">PATH</span><span class="o">=</span><span class="s2">&quot;/Library/Frameworks/PythonT.framework/Versions/3.13/bin&quot;</span>:<span class="s2">&quot;</span><span class="nv">$PATH</span><span class="s2">&quot;</span>
</pre></div>
</div>
<p>The traditional framework installation by default does something similar,
except for <code class="file docutils literal notranslate"><span class="pre">Python.framework</span></code>. Be aware that having both framework <code class="docutils literal notranslate"><span class="pre">bin</span></code>
directories in <code class="docutils literal notranslate"><span class="pre">PATH</span></code> can lead to confusion if there are duplicate names
like <code class="docutils literal notranslate"><span class="pre">python3.13</span></code> in both; which one is actually used depends on the order
they appear in <code class="docutils literal notranslate"><span class="pre">PATH</span></code>. The <code class="docutils literal notranslate"><span class="pre">which</span> <span class="pre">python3.x</span></code> or <code class="docutils literal notranslate"><span class="pre">which</span> <span class="pre">python3.xt</span></code>
commands can show which path is being used. Using virtual environments
can help avoid such ambiguities. Another option might be to create
a shell <strong class="command">alias</strong> to the desired interpreter, like:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="nb">alias</span><span class="w"> </span>py3.13<span class="o">=</span><span class="s2">&quot;/Library/Frameworks/Python.framework/Versions/3.13/bin/python3.13&quot;</span>
<span class="nb">alias</span><span class="w"> </span>py3.13t<span class="o">=</span><span class="s2">&quot;/Library/Frameworks/PythonT.framework/Versions/3.13/bin/python3.13t&quot;</span>
</pre></div>
</div>
</li>
</ul>
</section>
<section id="installing-using-the-command-line">
<h3><span class="section-number">5.5.2. </span>Installing using the command line<a class="headerlink" href="#installing-using-the-command-line" title="Link to this heading"></a></h3>
<p>If you want to use automation to install the <code class="docutils literal notranslate"><span class="pre">python.org</span></code> installer package
(rather than by using the familiar macOS <strong class="program">Installer</strong> GUI app),
the macOS command line <strong class="command">installer</strong> utility lets you select non-default
options, too. If you are not familiar with <strong class="command">installer</strong>, it can be
somewhat cryptic (see <strong class="command">man installer</strong> for more information).
As an example, the following shell snippet shows one way to do it,
using the <code class="docutils literal notranslate"><span class="pre">3.13.0b2</span></code> release and selecting the free-threaded interpreter
option:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="nv">RELEASE</span><span class="o">=</span><span class="s2">&quot;python-3.13.0b2-macos11.pkg&quot;</span>
<span class="c1"># download installer pkg</span>
curl<span class="w"> </span>-O<span class="w"> </span>https://www.python.org/ftp/python/3.13.0/<span class="si">${</span><span class="nv">RELEASE</span><span class="si">}</span>
<span class="c1"># create installer choicechanges to customize the install:</span>
<span class="c1"># enable the PythonTFramework-3.13 package</span>
<span class="c1"># while accepting the other defaults (install all other packages)</span>
cat<span class="w"> </span>&gt;<span class="w"> </span>./choicechanges.plist<span class="w"> </span><span class="s">&lt;&lt;EOF</span>
<span class="s">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;</span>
<span class="s">&lt;!DOCTYPE plist PUBLIC &quot;-//Apple//DTD PLIST 1.0//EN&quot; &quot;http://www.apple.com/DTDs/PropertyList-1.0.dtd&quot;&gt;</span>
<span class="s">&lt;plist version=&quot;1.0&quot;&gt;</span>
<span class="s">&lt;array&gt;</span>
<span class="s"> &lt;dict&gt;</span>
<span class="s"> &lt;key&gt;attributeSetting&lt;/key&gt;</span>
<span class="s"> &lt;integer&gt;1&lt;/integer&gt;</span>
<span class="s"> &lt;key&gt;choiceAttribute&lt;/key&gt;</span>
<span class="s"> &lt;string&gt;selected&lt;/string&gt;</span>
<span class="s"> &lt;key&gt;choiceIdentifier&lt;/key&gt;</span>
<span class="s"> &lt;string&gt;org.python.Python.PythonTFramework-3.13&lt;/string&gt;</span>
<span class="s"> &lt;/dict&gt;</span>
<span class="s">&lt;/array&gt;</span>
<span class="s">&lt;/plist&gt;</span>
<span class="s">EOF</span>
sudo<span class="w"> </span>installer<span class="w"> </span>-pkg<span class="w"> </span>./<span class="si">${</span><span class="nv">RELEASE</span><span class="si">}</span><span class="w"> </span>-applyChoiceChangesXML<span class="w"> </span>./choicechanges.plist<span class="w"> </span>-target<span class="w"> </span>/
</pre></div>
</div>
<p>You can then test that both installer builds are now available with something like:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="c1"># test that the free-threaded interpreter was installed if the Unix Command Tools package was enabled</span>
<span class="gp">$ </span>/usr/local/bin/python3.13t<span class="w"> </span>-VV
<span class="go">Python 3.13.0b2 experimental free-threading build (v3.13.0b2:3a83b172af, Jun 5 2024, 12:57:31) [Clang 15.0.0 (clang-1500.3.9.4)]</span>
<span class="gp">$ </span><span class="c1"># and the traditional interpreter</span>
<span class="gp">$ </span>/usr/local/bin/python3.13<span class="w"> </span>-VV
<span class="go">Python 3.13.0b2 (v3.13.0b2:3a83b172af, Jun 5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]</span>
<span class="gp">$ </span><span class="c1"># test that they are also available without the prefix if /usr/local/bin is on $PATH</span>
<span class="gp">$ </span>python3.13t<span class="w"> </span>-VV
<span class="go">Python 3.13.0b2 experimental free-threading build (v3.13.0b2:3a83b172af, Jun 5 2024, 12:57:31) [Clang 15.0.0 (clang-1500.3.9.4)]</span>
<span class="gp">$ </span>python3.13<span class="w"> </span>-VV
<span class="go">Python 3.13.0b2 (v3.13.0b2:3a83b172af, Jun 5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Current <code class="docutils literal notranslate"><span class="pre">python.org</span></code> installers only install to fixed locations like
<code class="file docutils literal notranslate"><span class="pre">/Library/Frameworks/</span></code>, <code class="file docutils literal notranslate"><span class="pre">/Applications</span></code>, and <code class="file docutils literal notranslate"><span class="pre">/usr/local/bin</span></code>.
You cannot use the <strong class="command">installer</strong> <code class="docutils literal notranslate"><span class="pre">-domain</span></code> option to install to
other locations.</p>
</div>
</section>
<section id="distributing-python-applications">
<span id="distributing-python-applications-on-the-mac"></span><h3><span class="section-number">5.5.3. </span>Distributing Python Applications<a class="headerlink" href="#distributing-python-applications" title="Link to this heading"></a></h3>
<p>A range of tools exist for converting your Python code into a standalone
distributable application:</p>
<ul class="simple">
<li><p><a class="extlink-pypi reference external" href="https://pypi.org/project/py2app/">py2app</a>: Supports creating macOS <code class="docutils literal notranslate"><span class="pre">.app</span></code>
bundles from a Python project.</p></li>
<li><p><a class="reference external" href="https://briefcase.readthedocs.io">Briefcase</a>: Part of the <a class="reference external" href="https://beeware.org">BeeWare Project</a>; a cross-platform packaging tool that supports
creation of <code class="docutils literal notranslate"><span class="pre">.app</span></code> bundles on macOS, as well as managing signing and
notarization.</p></li>
<li><p><a class="reference external" href="https://pyinstaller.org/">PyInstaller</a>: A cross-platform packaging tool that creates
a single file or folder as a distributable artifact.</p></li>
</ul>
</section>
<section id="app-store-compliance">
<h3><span class="section-number">5.5.4. </span>App Store Compliance<a class="headerlink" href="#app-store-compliance" title="Link to this heading"></a></h3>
<p>Apps submitted for distribution through the macOS App Store must pass Apple’s
app review process. This process includes a set of automated validation rules
that inspect the submitted application bundle for problematic code.</p>
<p>The Python standard library contains some code that is known to violate these
automated rules. While these violations appear to be false positives, Apple’s
review rules cannot be challenged. Therefore, it is necessary to modify the
Python standard library for an app to pass App Store review.</p>
<p>The Python source tree contains
<a class="extlink-source reference external" href="https://github.com/python/cpython/tree/3.13/Mac/Resources/app-store-compliance.patch">a patch file</a> that will remove
all code that is known to cause issues with the App Store review process. This
patch is applied automatically when CPython is configured with the
<a class="reference internal" href="configure.html#cmdoption-with-app-store-compliance"><code class="xref std std-option docutils literal notranslate"><span class="pre">--with-app-store-compliance</span></code></a> option.</p>
<p>This patch is not normally required to use CPython on a Mac; nor is it required
if you are distributing an app <em>outside</em> the macOS App Store. It is <em>only</em>
required if you are using the macOS App Store as a distribution channel.</p>
</section>
</section>
<section id="other-resources">
<h2><span class="section-number">5.6. </span>Other Resources<a class="headerlink" href="#other-resources" title="Link to this heading"></a></h2>
<p>The <a class="reference external" href="https://www.python.org/about/help/">python.org Help page</a> has links to many useful resources.
The <a class="reference external" href="https://www.python.org/community/sigs/current/pythonmac-sig/">Pythonmac-SIG mailing list</a>
is another support resource specifically for Python users and developers on the Mac.</p>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">5. Using Python on macOS</a><ul>
<li><a class="reference internal" href="#using-python-for-macos-from-python-org">5.1. Using Python for macOS from <code class="docutils literal notranslate"><span class="pre">python.org</span></code></a><ul>
<li><a class="reference internal" href="#installation-steps">5.1.1. Installation steps</a></li>
<li><a class="reference internal" href="#how-to-run-a-python-script">5.1.2. How to run a Python script</a></li>
</ul>
</li>
<li><a class="reference internal" href="#alternative-distributions">5.2. Alternative Distributions</a></li>
<li><a class="reference internal" href="#installing-additional-python-packages">5.3. Installing Additional Python Packages</a></li>
<li><a class="reference internal" href="#gui-programming">5.4. GUI Programming</a></li>
<li><a class="reference internal" href="#advanced-topics">5.5. Advanced Topics</a><ul>
<li><a class="reference internal" href="#installing-free-threaded-binaries">5.5.1. Installing Free-threaded Binaries</a></li>
<li><a class="reference internal" href="#installing-using-the-command-line">5.5.2. Installing using the command line</a></li>
<li><a class="reference internal" href="#distributing-python-applications">5.5.3. Distributing Python Applications</a></li>
<li><a class="reference internal" href="#app-store-compliance">5.5.4. App Store Compliance</a></li>
</ul>
</li>
<li><a class="reference internal" href="#other-resources">5.6. Other Resources</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="windows.html"
title="previous chapter"><span class="section-number">4. </span>Using Python on Windows</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="android.html"
title="next chapter"><span class="section-number">6. </span>Using Python on Android</a></p>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a Bug</a></li>
<li>
<a href="https://github.com/python/cpython/blob/main/Doc/using/mac.rst"
rel="nofollow">Show Source
</a>
</li>
</ul>
</div>
</div>
<div id="sidebarbutton" title="Collapse sidebar">
<span>«</span>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="android.html" title="6. Using Python on Android"
>next</a> |</li>
<li class="right" >
<a href="windows.html" title="4. Using Python on Windows"
>previous</a> |</li>
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.13.3 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python Setup and Usage</a> &#187;</li>
<li class="nav-item nav-item-this"><a href=""><span class="section-number">5. </span>Using Python on macOS</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />
<input type="submit" value="Go" />
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="footer">
&copy;
<a href="../copyright.html">
Copyright
</a>
2001-2025, Python Software Foundation.
<br />
This page is licensed under the Python Software Foundation License Version 2.
<br />
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
<br />
See <a href="/license.html">History and License</a> for more information.<br />
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
<br />
Last updated on Apr 08, 2025 (14:33 UTC).
<a href="/bugs.html">Found a bug</a>?
<br />
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink