5.1.1.Installation steps¶

Forcurrent Python versions(other than those insecurity status), the release team produces aPython for macOS installer package for each new release.A list of available installersis availablehere.We recommend using the most recent supported Python version where possible.Current installers provide auniversal2 binary buildof Python which runs natively on all Macs (Apple Silicon and Intel) that aresupported by a wide range of macOS versions,currently typically from at leastmacOS 10.13 High Sierra on.

The downloaded file is a standard macOS installer package file (.pkg).File integrity information (checksum, size, sigstore signature, etc) for each file is includedon the release download page. Installer packages and their contents are signed and notarizedwithPythonSoftwareFoundation Apple Developer ID certificatesto meetmacOS Gatekeeper requirements.

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 severalinstaller windows steps.

Clicking on theContinue button brings up theRead Me for this installer.Besides other important information, theRead Me documents which Python version isgoing to be installed and on what versions of macOS it is supported. You may needto scroll through to read the whole file. By default, thisRead Me will also beinstalled in/Applications/Python3.13/ and available to read anytime.

Clicking onContinue proceeds to display the license for Python and forother included software. You will then need toAgree to the license termsbefore proceeding to the next step. This license file will also be installedand available to be read later.

After the license terms are accepted, the next step is theInstallation Typedisplay. For most uses, the standard set of installation operations is appropriate.

By pressing theCustomize button, you can choose to omit or select certain packagecomponents of the installer. Click on each package name to see a description ofwhat it installs.To also install support for the optional experimental free-threaded feature,seeInstalling Free-threaded Binaries.

In either case, clickingInstall will begin the install process by askingpermission to install new software. A macOS user name withAdministrator privilegeis needed as the installed Python will be available to all users of the Mac.

When the installation is complete, theSummary window will appear.

Double-click on theInstall Certificates.commandicon or file in the/Applications/Python3.13/ window to complete theinstallation.

This will open a temporaryTerminal shell window thatwill use the new Python to download and install SSL root certificatesfor its use.

IfSuccessfullyinstalledcertifi andupdatecomplete appearsin the terminal window, the installation is complete.Close this terminal window and the installer window.

A default install will include:

• APython3.13 folder in yourApplications folder. In hereyou findIDLE, the development environment that is a standard part of officialPython distributions; andPython Launcher, which handles double-clicking Pythonscripts from the macOSFinder.

• A framework/Library/Frameworks/Python.framework, which includes thePython executable and libraries. The installer adds this location to your shellpath. To uninstall Python, you can remove these three things.Symlinks to the Python executable are placed in/usr/local/bin/.

5.1.2.How to run a Python script¶

There are two ways to invoke the Python interpreter.If you are familiar with using a Unix shell in a terminalwindow, you can invokepython3.13 orpython3 optionallyfollowed by one or more command line options (described inCommand line and environment).The Python tutorial also has a useful section onusing Python interactively from a shell.

You can also invoke the interpreter through an integrateddevelopment environment.IDLE — Python editor and shell is a basic editor and interpreter environmentwhich is included with the standard distribution of Python.IDLE includes a Help menu that allows you to access Python documentation. If youare completely new to Python, you can read the tutorial introductionin that document.

There are many other editors and IDEs available, seeEditors and IDEsfor more information.

To run a Python script file from the terminal window, you caninvoke the interpreter with the name of the script file:

python3.13myscript.py

To run your script from the Finder, you can either:

• Drag it toPython Launcher.

• SelectPython Launcher as the default application to open yourscript (or any.py script) through the Finder Info window and double-click it.Python Launcher has various preferences to control how your script islaunched. Option-dragging allows you to change these for one invocation, or useitsPreferences menu to change things globally.

Be aware that running the script directly from the macOS Finder mightproduce different results than when running from a terminal window asthe script will not be run in the usual shell environment includingany setting of environment variables in shell profiles.And, as with any other script or program,be certain of what you are about to run.

5.5.1.Installing Free-threaded Binaries¶

Thepython.orgPython for macOSinstaller package can optionally install an additional build ofPython 3.13 that supportsPEP 703, the experimental free-threading feature(running with theglobal interpreter lock disabled).Check the release page onpython.org for possible updated information.

Because this feature is still considered experimental, the support for itis not installed by default. It is packaged as a separate install option,available by clicking theCustomize button on theInstallation Typestep of the installer as described above.

If the box next to theFree-threaded Python package name is checked,a separatePythonT.framework will also be installedalongside the normalPython.framework in/Library/Frameworks.This configuration allows a free-threaded Python 3.13 build to co-existon your system with a traditional (GIL only) Python 3.13 build withminimal risk while installing or testing. This installation layout is itselfexperimental and is subject to change in future releases.

Known cautions and limitations:

• TheUNIX command-line tools package, which is selected by default,will install links in/usr/local/bin forpython3.13t,the free-threaded interpreter, andpython3.13t-config,a configuration utility which may be useful for package builders.Since/usr/local/bin is typically included in your shellPATH,in most cases no changes to yourPATH environment variables shouldbe needed to usepython3.13t.

• For this release, theShell profile updater package and theUpdateShellProfile.command in/Applications/Python3.13/do not support the free-threaded package.

• The free-threaded build and the traditional build have separate searchpaths and separatesite-packages 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 ofpip for usewithpython3.13t.

  • To install a package usingpip without avenv:

    python3.13t-mpipinstall<package_name>

• When working with multiple Python environments, it is usually safest and easiesttocreate and use virtual environments.This can avoid possible command name conflicts and confusion about which Python is in use:

  python3.13t-mvenv<venv_name>

  thenactivate.

• To run a free-threaded version of IDLE:

  python3.13t-midlelib

• The interpreters in both builds respond to the samePYTHON environment variableswhich may have unexpected results, for example, if you havePYTHONPATHset in a shell profile. If necessary, there arecommand line options like-Eto ignore these environment variables.

• The free-threaded build links to the third-party shared libraries,such asOpenSSL andTk, installed in the traditional framework.This means that both builds also share one set of trust certificatesas installed by theInstall Certificates.command script,thus it only needs to be run once.

• If you cannot depend on the link in/usr/local/bin pointing to thepython.org free-threadedpython3.13t (for example, if you wantto install your own version there or some other distribution does),you can explicitly set your shellPATH environment variable toinclude thePythonT frameworkbin directory:

  exportPATH="/Library/Frameworks/PythonT.framework/Versions/3.13/bin":"$PATH"

  The traditional framework installation by default does something similar,except forPython.framework. Be aware that having both frameworkbindirectories inPATH can lead to confusion if there are duplicate nameslikepython3.13 in both; which one is actually used depends on the orderthey appear inPATH. Thewhichpython3.x orwhichpython3.xtcommands can show which path is being used. Using virtual environmentscan help avoid such ambiguities. Another option might be to createa shellalias to the desired interpreter, like:

  aliaspy3.13="/Library/Frameworks/Python.framework/Versions/3.13/bin/python3.13"aliaspy3.13t="/Library/Frameworks/PythonT.framework/Versions/3.13/bin/python3.13t"

5.5.2.Installing using the command line¶

If you want to use automation to install thepython.org installer package(rather than by using the familiar macOSInstaller GUI app),the macOS command lineinstaller utility lets you select non-defaultoptions, too. If you are not familiar withinstaller, it can besomewhat cryptic (seeman installer for more information).As an example, the following shell snippet shows one way to do it,using the3.13.0b2 release and selecting the free-threaded interpreteroption:

RELEASE="python-3.13.0b2-macos11.pkg"# download installer pkgcurl-Ohttps://www.python.org/ftp/python/3.13.0/${RELEASE}# create installer choicechanges to customize the install:#    enable the PythonTFramework-3.13 package#    while accepting the other defaults (install all other packages)cat>./choicechanges.plist<<EOF<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plist version="1.0"><array>        <dict>                <key>attributeSetting</key>                <integer>1</integer>                <key>choiceAttribute</key>                <string>selected</string>                <key>choiceIdentifier</key>                <string>org.python.Python.PythonTFramework-3.13</string>        </dict></array></plist>EOFsudoinstaller-pkg./${RELEASE}-applyChoiceChangesXML./choicechanges.plist-target/

You can then test that both installer builds are now available with something like:

$# test that the free-threaded interpreter was installed if the Unix Command Tools package was enabled$/usr/local/bin/python3.13t-VVPython 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)]$#    and the traditional interpreter$/usr/local/bin/python3.13-VVPython 3.13.0b2 (v3.13.0b2:3a83b172af, Jun  5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]$# test that they are also available without the prefix if /usr/local/bin is on $PATH$python3.13t-VVPython 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)]$python3.13-VVPython 3.13.0b2 (v3.13.0b2:3a83b172af, Jun  5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]

5.5.3.Distributing Python Applications¶

A range of tools exist for converting your Python code into a standalonedistributable application:

• py2app: Supports creating macOS.appbundles from a Python project.

• Briefcase: Part of theBeeWare Project; a cross-platform packaging tool that supportscreation of.app bundles on macOS, as well as managing signing andnotarization.

• PyInstaller: A cross-platform packaging tool that createsa single file or folder as a distributable artifact.

5.5.4.App Store Compliance¶

Apps submitted for distribution through the macOS App Store must pass Apple’sapp review process. This process includes a set of automated validation rulesthat inspect the submitted application bundle for problematic code.

The Python standard library contains some code that is known to violate theseautomated rules. While these violations appear to be false positives, Apple’sreview rules cannot be challenged. Therefore, it is necessary to modify thePython standard library for an app to pass App Store review.

The Python source tree containsa patch file that will removeall code that is known to cause issues with the App Store review process. Thispatch is applied automatically when CPython is configured with the--with-app-store-compliance option.

This patch is not normally required to use CPython on a Mac; nor is it requiredif you are distributing an appoutside the macOS App Store. It isonlyrequired if you are using the macOS App Store as a distribution channel.