mirror of https://github.com/python/cpython
475 lines
20 KiB
ReStructuredText
475 lines
20 KiB
ReStructuredText
|
|
.. _using-on-mac:
|
|
|
|
*********************
|
|
Using Python on macOS
|
|
*********************
|
|
|
|
.. sectionauthor:: Bob Savage <bobsavage@mac.com>
|
|
.. sectionauthor:: Ned Deily <nad@python.org>
|
|
|
|
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.
|
|
|
|
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 `python.org website <https://www.python.org/downloads/>`_. See
|
|
:ref:`alternative_bundles` for some other options.
|
|
|
|
.. |usemac_x_dot_y| replace:: 3.13
|
|
.. |usemac_python_x_dot_y_literal| replace:: ``python3.13``
|
|
.. |usemac_python_x_dot_y_t_literal| replace:: ``python3.13t``
|
|
.. |usemac_python_x_dot_y_t_literal_config| replace:: ``python3.13t-config``
|
|
.. |usemac_applications_folder_name| replace:: ``Python 3.13``
|
|
.. |usemac_applications_folder_version| replace:: ``/Applications/Python 3.13/``
|
|
|
|
.. _getting-osx:
|
|
.. _getting-and-installing-macpython:
|
|
|
|
Using Python for macOS from ``python.org``
|
|
==========================================
|
|
|
|
Installation steps
|
|
------------------
|
|
|
|
For `current Python versions <https://www.python.org/downloads/>`_
|
|
(other than those in ``security`` status), the release team produces a
|
|
**Python for macOS** installer package for each new release.
|
|
A list of available installers
|
|
is available `here <https://www.python.org/downloads/macos/>`_.
|
|
We recommend using the most recent supported Python version where possible.
|
|
Current installers provide a
|
|
`universal2 binary <https://en.wikipedia.org/wiki/Universal_binary>`_ 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 **macOS 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 included
|
|
on the release download page. Installer packages and their contents are signed and notarized
|
|
with ``Python Software Foundation`` Apple Developer ID certificates
|
|
to meet `macOS Gatekeeper requirements <https://support.apple.com/en-us/102445>`_.
|
|
|
|
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.
|
|
|
|
.. image:: mac_installer_01_introduction.png
|
|
|
|
Clicking on the **Continue** button brings up the **Read Me** for this installer.
|
|
Besides other important information, the **Read Me** 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 **Read Me** will also be
|
|
installed in |usemac_applications_folder_version| and available to read anytime.
|
|
|
|
.. image:: mac_installer_02_readme.png
|
|
|
|
Clicking on **Continue** proceeds to display the license for Python and for
|
|
other included software. You will then need to **Agree** to the license terms
|
|
before proceeding to the next step. This license file will also be installed
|
|
and available to be read later.
|
|
|
|
.. image:: mac_installer_03_license.png
|
|
|
|
After the license terms are accepted, the next step is the **Installation Type**
|
|
display. For most uses, the standard set of installation operations is appropriate.
|
|
|
|
.. image:: mac_installer_04_installation_type.png
|
|
|
|
By pressing the **Customize** 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 :ref:`install-freethreaded-macos`.
|
|
|
|
.. image:: mac_installer_05_custom_install.png
|
|
|
|
In either case, clicking **Install** will begin the install process by asking
|
|
permission to install new software. A macOS user name with ``Administrator`` privilege
|
|
is needed as the installed Python will be available to all users of the Mac.
|
|
|
|
When the installation is complete, the **Summary** window will appear.
|
|
|
|
.. image:: mac_installer_06_summary.png
|
|
|
|
Double-click on the :command:`Install Certificates.command`
|
|
icon or file in the |usemac_applications_folder_version| window to complete the
|
|
installation.
|
|
|
|
.. image:: mac_installer_07_applications.png
|
|
|
|
This will open a temporary :program:`Terminal` shell window that
|
|
will use the new Python to download and install SSL root certificates
|
|
for its use.
|
|
|
|
.. image:: mac_installer_08_install_certificates.png
|
|
|
|
If ``Successfully installed certifi`` and ``update complete`` appears
|
|
in the terminal window, the installation is complete.
|
|
Close this terminal window and the installer window.
|
|
|
|
A default install will include:
|
|
|
|
* A |usemac_applications_folder_name| folder in your :file:`Applications` folder. In here
|
|
you find :program:`IDLE`, the development environment that is a standard part of official
|
|
Python distributions; and :program:`Python Launcher`, which handles double-clicking Python
|
|
scripts from the macOS `Finder <https://support.apple.com/en-us/HT201732>`_.
|
|
|
|
* A framework :file:`/Library/Frameworks/Python.framework`, 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 :file:`/usr/local/bin/`.
|
|
|
|
.. note::
|
|
|
|
Recent versions of macOS include a :command:`python3` command in :file:`/usr/bin/python3`
|
|
that links to a usually older and incomplete version of Python provided by and for use by
|
|
the Apple development tools, :program:`Xcode` or the :program:`Command Line Tools for Xcode`.
|
|
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 ``python.org``, you will have
|
|
two different but functional Python installations on your computer that
|
|
can co-exist. The default installer options should ensure that its :command:`python3`
|
|
will be used instead of the system :command:`python3`.
|
|
|
|
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 terminal
|
|
window, you can invoke |usemac_python_x_dot_y_literal| or ``python3`` optionally
|
|
followed by one or more command line options (described in :ref:`using-on-general`).
|
|
The Python tutorial also has a useful section on
|
|
:ref:`using Python interactively from a shell <tut-interac>`.
|
|
|
|
You can also invoke the interpreter through an integrated
|
|
development environment.
|
|
:ref:`idle` is a basic editor and interpreter environment
|
|
which is included with the standard distribution of Python.
|
|
:program:`IDLE` 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.
|
|
|
|
There are many other editors and IDEs available, see :ref:`editors`
|
|
for more information.
|
|
|
|
To run a Python script file from the terminal window, you can
|
|
invoke the interpreter with the name of the script file:
|
|
|
|
|usemac_python_x_dot_y_literal| ``myscript.py``
|
|
|
|
To run your script from the Finder, you can either:
|
|
|
|
* Drag it to :program:`Python Launcher`.
|
|
|
|
* Select :program:`Python Launcher` as the default application to open your
|
|
script (or any ``.py`` script) through the Finder Info window and double-click it.
|
|
:program:`Python Launcher` has various preferences to control how your script is
|
|
launched. Option-dragging allows you to change these for one invocation, or use
|
|
its ``Preferences`` menu to change things globally.
|
|
|
|
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.
|
|
|
|
.. _alternative_bundles:
|
|
|
|
Alternative Distributions
|
|
=========================
|
|
|
|
Besides the standard ``python.org`` for macOS installer, there are third-party
|
|
distributions for macOS that may include additional functionality.
|
|
Some popular distributions and their key features:
|
|
|
|
`ActivePython <https://www.activestate.com/products/python/>`_
|
|
Installer with multi-platform compatibility, documentation
|
|
|
|
`Anaconda <https://www.anaconda.com/download/>`_
|
|
Popular scientific modules (such as numpy, scipy, and pandas) and the
|
|
``conda`` package manager.
|
|
|
|
`Homebrew <https://brew.sh>`_
|
|
Package manager for macOS including multiple versions of Python and many
|
|
third-party Python-based packages (including numpy, scipy, and pandas).
|
|
|
|
`MacPorts <https://www.macports.org>`_
|
|
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.
|
|
|
|
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.
|
|
|
|
.. _mac-package-manager:
|
|
|
|
Installing Additional Python Packages
|
|
=====================================
|
|
|
|
Refer to the `Python Packaging User Guide`_ for more information.
|
|
|
|
.. _Python Packaging User Guide: https://packaging.python.org/en/latest/tutorials/installing-packages/
|
|
|
|
|
|
.. _osx-gui-scripts:
|
|
|
|
.. _gui-programming-on-the-mac:
|
|
|
|
GUI Programming
|
|
===============
|
|
|
|
There are several options for building GUI applications on the Mac with Python.
|
|
|
|
The standard Python GUI toolkit is :mod:`tkinter`, based on the cross-platform
|
|
Tk toolkit (https://www.tcl.tk). A macOS-native version of Tk is included with
|
|
the installer.
|
|
|
|
*PyObjC* is a Python binding to Apple's Objective-C/Cocoa framework.
|
|
Information on PyObjC is available from :pypi:`pyobjc`.
|
|
|
|
A number of alternative macOS GUI toolkits are available including:
|
|
|
|
* `PySide <https://www.qt.io/qt-for-python>`_: Official Python bindings to the
|
|
`Qt GUI toolkit <https://wiki.qt.io/Qt_for_Python>`_.
|
|
|
|
* `PyQt <https://riverbankcomputing.com/software/pyqt/>`_: Alternative
|
|
Python bindings to Qt.
|
|
|
|
* `Kivy <https://kivy.org>`_: A cross-platform GUI toolkit that supports
|
|
desktop and mobile platforms.
|
|
|
|
* `Toga <https://toga.readthedocs.io>`_: Part of the `BeeWare Project
|
|
<https://beeware.org>`_; supports desktop, mobile, web and console apps.
|
|
|
|
* `wxPython <https://wxpython.org>`_: A cross-platform toolkit that
|
|
supports desktop operating systems.
|
|
|
|
|
|
Advanced Topics
|
|
===============
|
|
|
|
.. _install-freethreaded-macos:
|
|
|
|
Installing Free-threaded Binaries
|
|
---------------------------------
|
|
|
|
.. versionadded:: 3.13 (Experimental)
|
|
|
|
.. note::
|
|
|
|
Everything described in this section is considered experimental,
|
|
and should be expected to change in future releases.
|
|
|
|
The ``python.org`` :ref:`Python for macOS <getting-and-installing-macpython>`
|
|
installer package can optionally install an additional build of
|
|
Python |usemac_x_dot_y| that supports :pep:`703`, the experimental free-threading feature
|
|
(running with the :term:`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.
|
|
|
|
.. image:: mac_installer_09_custom_install_free_threaded.png
|
|
|
|
If the box next to the **Free-threaded Python** package name is checked,
|
|
a separate :file:`PythonT.framework` will also be installed
|
|
alongside the normal :file:`Python.framework` in :file:`/Library/Frameworks`.
|
|
This configuration allows a free-threaded Python |usemac_x_dot_y| build to co-exist
|
|
on your system with a traditional (GIL only) Python |usemac_x_dot_y| 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 :file:`/usr/local/bin` for |usemac_python_x_dot_y_t_literal|,
|
|
the free-threaded interpreter, and |usemac_python_x_dot_y_t_literal_config|,
|
|
a configuration utility which may be useful for package builders.
|
|
Since :file:`/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 |usemac_python_x_dot_y_t_literal|.
|
|
|
|
- For this release, the **Shell profile updater** package and the
|
|
:file:`Update Shell Profile.command` in |usemac_applications_folder_version|
|
|
do not support the free-threaded package.
|
|
|
|
- The free-threaded build and the traditional build have separate search
|
|
paths and separate :file:`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 :program:`pip` for use
|
|
with |usemac_python_x_dot_y_t_literal|.
|
|
|
|
- To install a package using :command:`pip` without a :command:`venv`:
|
|
|
|
|usemac_python_x_dot_y_t_literal| ``-m pip install <package_name>``
|
|
|
|
- When working with multiple Python environments, it is usually safest and easiest
|
|
to :ref:`create and use virtual environments <tut-venv>`.
|
|
This can avoid possible command name conflicts and confusion about which Python is in use:
|
|
|
|
|usemac_python_x_dot_y_t_literal| ``-m venv <venv_name>``
|
|
|
|
then :command:`activate`.
|
|
|
|
- To run a free-threaded version of IDLE:
|
|
|
|
|usemac_python_x_dot_y_t_literal| ``-m idlelib``
|
|
|
|
- The interpreters in both builds respond to the same
|
|
:ref:`PYTHON environment variables <using-on-envvars>`
|
|
which may have unexpected results, for example, if you have ``PYTHONPATH``
|
|
set in a shell profile. If necessary, there are
|
|
:ref:`command line options <using-on-interface-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 :command:`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 |usemac_python_x_dot_y_t_literal| (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:
|
|
|
|
.. code-block:: sh
|
|
|
|
export PATH="/Library/Frameworks/PythonT.framework/Versions/3.13/bin":"$PATH"
|
|
|
|
The traditional framework installation by default does something similar,
|
|
except for :file:`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 :command:`alias` to the desired interpreter, like:
|
|
|
|
.. code-block:: sh
|
|
|
|
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"
|
|
|
|
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 :program:`Installer` GUI app),
|
|
the macOS command line :command:`installer` utility lets you select non-default
|
|
options, too. If you are not familiar with :command:`installer`, it can be
|
|
somewhat cryptic (see :command:`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:
|
|
|
|
.. code-block:: sh
|
|
|
|
RELEASE="python-3.13.0b2-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>
|
|
<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>
|
|
EOF
|
|
|
|
sudo installer -pkg ./${RELEASE} -applyChoiceChangesXML ./choicechanges.plist -target /
|
|
|
|
|
|
You can then test that both installer builds are now available with something like:
|
|
|
|
.. code-block:: console
|
|
|
|
$ # 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)]
|
|
|
|
.. note::
|
|
|
|
Current ``python.org`` installers only install to fixed locations like
|
|
:file:`/Library/Frameworks/`, :file:`/Applications`, and :file:`/usr/local/bin`.
|
|
You cannot use the :command:`installer` ``-domain`` option to install to
|
|
other locations.
|
|
|
|
.. _distributing-python-applications-on-the-mac:
|
|
|
|
Distributing Python Applications
|
|
--------------------------------
|
|
|
|
A range of tools exist for converting your Python code into a standalone
|
|
distributable application:
|
|
|
|
* :pypi:`py2app`: Supports creating macOS ``.app``
|
|
bundles from a Python project.
|
|
|
|
* `Briefcase <https://briefcase.readthedocs.io>`_: Part of the `BeeWare Project
|
|
<https://beeware.org>`_; a cross-platform packaging tool that supports
|
|
creation of ``.app`` bundles on macOS, as well as managing signing and
|
|
notarization.
|
|
|
|
* `PyInstaller <https://pyinstaller.org/>`_: A cross-platform packaging tool that creates
|
|
a single file or folder as a distributable artifact.
|
|
|
|
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
|
|
:source:`a patch file <Mac/Resources/app-store-compliance.patch>` 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
|
|
:option:`--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.
|
|
|
|
Other Resources
|
|
===============
|
|
|
|
The `python.org Help page <https://www.python.org/about/help/>`_ has links to many useful resources.
|
|
The `Pythonmac-SIG mailing list <https://www.python.org/community/sigs/current/pythonmac-sig/>`_
|
|
is another support resource specifically for Python users and developers on the Mac.
|