There are several options for building GUI applications on the Mac with Python.
A number of alternative macOS GUI toolkits are available including:
5.5.1.
Installing Free-threaded Binaries
Added in version 3.13:
(Experimental)
Everything described in this section is considered experimental,
and should be expected to change in future releases.
The
python.org
Python for macOS
installer package can optionally install an additional build of
Python 3.13 that supports
PEP 703
, the experimental free-threading feature
(running with the
global interpreter lock
disabled).
Check the release page on
python.org
for possible updated information.
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
Customize
button on the
Installation Type
step of the installer as described above.
If the box next to the
Free-threaded Python
package name is checked,
a separate
PythonT.framework
will also be installed
alongside the normal
Python.framework
in
/Library/Frameworks
.
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.
Known cautions and limitations:
The
UNIX command-line tools
package, which is selected by default,
will install links in
/usr/local/bin
for
python3.13t
,
the free-threaded interpreter, and
python3.13t-config
,
a configuration utility which may be useful for package builders.
Since
/usr/local/bin
is typically included in your shell
PATH
,
in most cases no changes to your
PATH
environment variables should
be needed to use
python3.13t
.
For this release, the
Shell profile updater
package and the
Update
Shell
Profile.command
in
/Applications/Python
3.13/
do not support the free-threaded package.
The free-threaded build and the traditional build have separate search
paths and separate
site-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 of
pip
for use
with
python3.13t
.
To install a package using
pip
without a
venv
:
python3.13t -m pip install <package_name>
When working with multiple Python environments, it is usually safest and easiest
to
create and use virtual environments
.
This can avoid possible command name conflicts and confusion about which Python is in use:
python3.13t -m venv <venv_name>
then
activate
.
To run a free-threaded version of IDLE:
python3.13t -m idlelib
The interpreters in both builds respond to the same
PYTHON environment variables
which may have unexpected results, for example, if you have
PYTHONPATH
set in a shell profile. If necessary, there are
command line options
like
-E
to ignore these environment variables.
The free-threaded build links to the third-party shared libraries,
such as
OpenSSL
and
Tk
, installed in the traditional framework.
This means that both builds also share one set of trust certificates
as installed by the
Install Certificates.command
script,
thus it only needs to be run once.
If you cannot depend on the link in
/usr/local/bin
pointing to the
python.org
free-threaded
python3.13t
(for example, if you want
to install your own version there or some other distribution does),
you can explicitly set your shell
PATH
environment variable to
include the
PythonT
framework
bin
directory:
export PATH="/Library/Frameworks/PythonT.framework/Versions/3.13/bin":"$PATH"
The traditional framework installation by default does something similar,
except for
Python.framework
. Be aware that having both framework
bin
directories in
PATH
can lead to confusion if there are duplicate names
like
python3.13
in both; which one is actually used depends on the order
they appear in
PATH
. The
which
python3.x
or
which
python3.xt
commands can show which path is being used. Using virtual environments
can help avoid such ambiguities. Another option might be to create
a shell
alias
to the desired interpreter, like:
alias py3.13="/Library/Frameworks/Python.framework/Versions/3.13/bin/python3.13"
alias py3.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 the
python.org
installer package
(rather than by using the familiar macOS
Installer
GUI app),
the macOS command line
installer
utility lets you select non-default
options, too. If you are not familiar with
installer
, it can be
somewhat cryptic (see
man installer
for more information).
As an example, the following shell snippet shows one way to do it,
using the
3.13.0b2
release and selecting the free-threaded interpreter
option:
RELEASE="python-3.130b2-macos11.pkg"
# download installer pkg
curl -O https://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>
<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>
sudo installer -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 -VV
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)]
$ # and the traditional interpreter
$ /usr/local/bin/python3.13 -VV
Python 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 -VV
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)]
$ python3.13 -VV
Python 3.13.0b2 (v3.13.0b2:3a83b172af, Jun 5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]
Current
python.org
installers only install to fixed locations like
/Library/Frameworks/
,
/Applications
, and
/usr/local/bin
.
You cannot use the
installer
-domain
option to install to
other locations.
5.5.3.
Distributing Python Applications
A range of tools exist for converting your Python code into a standalone
distributable application:
py2app
: Supports creating macOS
.app
bundles from a Python project.
Briefcase
: Part of the
BeeWare Project
; a cross-platform packaging tool that supports
creation of
.app
bundles on macOS, as well as managing signing and
notarization.
PyInstaller
: A cross-platform packaging tool that creates
a 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’s
app review process. This process includes a set of automated validation rules
that inspect the submitted application bundle for problematic code.
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.
The Python source tree contains
a patch file
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
--with-app-store-compliance
option.
This patch is not normally required to use CPython on a Mac; nor is it required
if you are distributing an app
outside
the macOS App Store. It is
only
required if you are using the macOS App Store as a distribution channel.
5.6.
Other Resources
The
python.org Help page
has links to many useful resources.
The
Pythonmac-SIG mailing list
is another support resource specifically for Python users and developers on the Mac.
5. Using Python on macOS
