Debian Codegraph @

Doc/using/mac.rst

raw
1 .. highlight:: none
2
3 .. _using-on-mac:
4
5 *********************
6 Using Python on macOS
7 *********************
8
9 .. sectionauthor:: Bob Savage <[email protected]>
10 .. sectionauthor:: Ned Deily <[email protected]>
11
12 This document aims to give an overview of macOS-specific behavior you should
13 know about to get started with Python on Mac computers.
14 Python on a Mac running macOS is very similar to Python on other Unix-derived platforms,
15 but there are some differences in installation and some features.
16
17 There are various ways to obtain and install Python for macOS.
18 Pre-built versions of the most recent versions of Python are available
19 from a number of distributors. Much of this document describes use of
20 the Pythons provided by the CPython release team for download from
21 the `python.org website <https://www.python.org/downloads/>`_. See
22 :ref:`alternative_bundles` for some other options.
23
24 .. _getting-osx:
25 .. _getting-and-installing-macpython:
26
27 Using Python for macOS from ``python.org``
28 ==========================================
29
30 Installation steps
31 ------------------
32
33 For `current Python versions <https://www.python.org/downloads/>`_
34 (other than those in ``security`` status), the release team produces a
35 **Python for macOS** installer package for each new release.
36 A list of available installers
37 is available `here <https://www.python.org/downloads/macos/>`_.
38 We recommend using the most recent supported Python version where possible.
39 Current installers provide a
40 `universal2 binary <https://en.wikipedia.org/wiki/Universal_binary>`_ build
41 of Python which runs natively on all Macs (Apple Silicon and Intel) that are
42 supported by a wide range of macOS versions,
43 currently typically from at least **macOS 10.13 High Sierra** on.
44
45 The downloaded file is a standard macOS installer package file (``.pkg``).
46 File integrity information (checksum, size, sigstore signature, etc) for each file is included
47 on the release download page. Installer packages and their contents are signed and notarized
48 with ``Python Software Foundation`` Apple Developer ID certificates
49 to meet `macOS Gatekeeper requirements <https://support.apple.com/en-us/102445>`_.
50
51 For a default installation, double-click on the downloaded installer package file.
52 This should launch the standard macOS Installer app and display the first of several
53 installer windows steps.
54
55 .. image:: mac_installer_01_introduction.png
56
57 Clicking on the **Continue** button brings up the **Read Me** for this installer.
58 Besides other important information, the **Read Me** documents which Python version is
59 going to be installed and on what versions of macOS it is supported. You may need
60 to scroll through to read the whole file. By default, this **Read Me** will also be
61 installed in |applications_python_version_literal| and available to read anytime.
62
63 .. image:: mac_installer_02_readme.png
64
65 Clicking on **Continue** proceeds to display the license for Python and for
66 other included software. You will then need to **Agree** to the license terms
67 before proceeding to the next step. This license file will also be installed
68 and available to be read later.
69
70 .. image:: mac_installer_03_license.png
71
72 After the license terms are accepted, the next step is the **Installation Type**
73 display. For most uses, the standard set of installation operations is appropriate.
74
75 .. image:: mac_installer_04_installation_type.png
76
77 By pressing the **Customize** button, you can choose to omit or select certain package
78 components of the installer. Click on each package name to see a description of
79 what it installs.
80 To also install support for the optional experimental free-threaded feature,
81 see :ref:`install-freethreaded-macos`.
82
83 .. image:: mac_installer_05_custom_install.png
84
85 In either case, clicking **Install** will begin the install process by asking
86 permission to install new software. A macOS user name with ``Administrator`` privilege
87 is needed as the installed Python will be available to all users of the Mac.
88
89 When the installation is complete, the **Summary** window will appear.
90
91 .. image:: mac_installer_06_summary.png
92
93 Double-click on the :command:`Install Certificates.command`
94 icon or file in the |applications_python_version_literal| window to complete the
95 installation.
96
97 .. image:: mac_installer_07_applications.png
98
99 This will open a temporary :program:`Terminal` shell window that
100 will use the new Python to download and install SSL root certificates
101 for its use.
102
103 .. image:: mac_installer_08_install_certificates.png
104
105 If ``Successfully installed certifi`` and ``update complete`` appears
106 in the terminal window, the installation is complete.
107 Close this terminal window and the installer window.
108
109 A default install will include:
110
111 * A |python_version_literal| folder in your :file:`Applications` folder. In here
112 you find :program:`IDLE`, the development environment that is a standard part of official
113 Python distributions; and :program:`Python Launcher`, which handles double-clicking Python
114 scripts from the macOS `Finder <https://support.apple.com/en-us/HT201732>`_.
115
116 * A framework :file:`/Library/Frameworks/Python.framework`, which includes the
117 Python executable and libraries. The installer adds this location to your shell
118 path. To uninstall Python, you can remove these three things.
119 Symlinks to the Python executable are placed in :file:`/usr/local/bin/`.
120
121 .. note::
122
123 Recent versions of macOS include a :command:`python3` command in :file:`/usr/bin/python3`
124 that links to a usually older and incomplete version of Python provided by and for use by
125 the Apple development tools, :program:`Xcode` or the :program:`Command Line Tools for Xcode`.
126 You should never modify or attempt to delete this installation, as it is
127 Apple-controlled and is used by Apple-provided or third-party software. If
128 you choose to install a newer Python version from ``python.org``, you will have
129 two different but functional Python installations on your computer that
130 can co-exist. The default installer options should ensure that its :command:`python3`
131 will be used instead of the system :command:`python3`.
132
133 How to run a Python script
134 --------------------------
135
136 There are two ways to invoke the Python interpreter.
137 If you are familiar with using a Unix shell in a terminal
138 window, you can invoke |python_x_dot_y_literal| or ``python3`` optionally
139 followed by one or more command line options (described in :ref:`using-on-general`).
140 The Python tutorial also has a useful section on
141 :ref:`using Python interactively from a shell <tut-interac>`.
142
143 You can also invoke the interpreter through an integrated
144 development environment.
145 :ref:`idle` is a basic editor and interpreter environment
146 which is included with the standard distribution of Python.
147 :program:`IDLE` includes a Help menu that allows you to access Python documentation. If you
148 are completely new to Python, you can read the tutorial introduction
149 in that document.
150
151 There are many other editors and IDEs available, see :ref:`editors`
152 for more information.
153
154 To run a Python script file from the terminal window, you can
155 invoke the interpreter with the name of the script file:
156
157 |python_x_dot_y_literal| ``myscript.py``
158
159 To run your script from the Finder, you can either:
160
161 * Drag it to :program:`Python Launcher`.
162
163 * Select :program:`Python Launcher` as the default application to open your
164 script (or any ``.py`` script) through the Finder Info window and double-click it.
165 :program:`Python Launcher` has various preferences to control how your script is
166 launched. Option-dragging allows you to change these for one invocation, or use
167 its ``Preferences`` menu to change things globally.
168
169 Be aware that running the script directly from the macOS Finder might
170 produce different results than when running from a terminal window as
171 the script will not be run in the usual shell environment including
172 any setting of environment variables in shell profiles.
173 And, as with any other script or program,
174 be certain of what you are about to run.
175
176 .. _alternative_bundles:
177
178 Alternative Distributions
179 =========================
180
181 Besides the standard ``python.org`` for macOS installer, there are third-party
182 distributions for macOS that may include additional functionality.
183 Some popular distributions and their key features:
184
185 `ActivePython <https://www.activestate.com/products/python/>`_
186 Installer with multi-platform compatibility, documentation
187
188 `Anaconda <https://www.anaconda.com/download/>`_
189 Popular scientific modules (such as numpy, scipy, and pandas) and the
190 ``conda`` package manager.
191
192 `Homebrew <https://brew.sh>`_
193 Package manager for macOS including multiple versions of Python and many
194 third-party Python-based packages (including numpy, scipy, and pandas).
195
196 `MacPorts <https://www.macports.org>`_
197 Another package manager for macOS including multiple versions of Python and many
198 third-party Python-based packages. May include pre-built versions of Python and
199 many packages for older versions of macOS.
200
201 Note that distributions might not include the latest versions of Python or
202 other libraries, and are not maintained or supported by the core Python team.
203
204 .. _mac-package-manager:
205
206 Installing Additional Python Packages
207 =====================================
208
209 Refer to the `Python Packaging User Guide`_ for more information.
210
211 .. _Python Packaging User Guide: https://packaging.python.org/en/latest/tutorials/installing-packages/
212
213
214 .. _osx-gui-scripts:
215
216 .. _gui-programming-on-the-mac:
217
218 GUI Programming
219 ===============
220
221 There are several options for building GUI applications on the Mac with Python.
222
223 The standard Python GUI toolkit is :mod:`tkinter`, based on the cross-platform
224 Tk toolkit (https://www.tcl.tk). A macOS-native version of Tk is included with
225 the installer.
226
227 *PyObjC* is a Python binding to Apple's Objective-C/Cocoa framework.
228 Information on PyObjC is available from :pypi:`pyobjc`.
229
230 A number of alternative macOS GUI toolkits are available including:
231
232 * `PySide <https://www.qt.io/qt-for-python>`_: Official Python bindings to the
233 `Qt GUI toolkit <https://wiki.qt.io/Qt_for_Python>`_.
234
235 * `PyQt <https://riverbankcomputing.com/software/pyqt/>`_: Alternative
236 Python bindings to Qt.
237
238 * `Kivy <https://kivy.org>`_: A cross-platform GUI toolkit that supports
239 desktop and mobile platforms.
240
241 * `Toga <https://toga.readthedocs.io>`_: Part of the `BeeWare Project
242 <https://beeware.org>`_; supports desktop, mobile, web and console apps.
243
244 * `wxPython <https://wxpython.org>`_: A cross-platform toolkit that
245 supports desktop operating systems.
246
247
248 Advanced Topics
249 ===============
250
251 .. _install-freethreaded-macos:
252
253 Installing Free-threaded Binaries
254 ---------------------------------
255
256 .. versionadded:: 3.13 (Experimental)
257
258 .. note::
259
260 Everything described in this section is considered experimental,
261 and should be expected to change in future releases.
262
263 The ``python.org`` :ref:`Python for macOS <getting-and-installing-macpython>`
264 installer package can optionally install an additional build of
265 Python |version| that supports :pep:`703`, the experimental free-threading feature
266 (running with the :term:`global interpreter lock` disabled).
267 Check the release page on ``python.org`` for possible updated information.
268
269 Because this feature is still considered experimental, the support for it
270 is not installed by default. It is packaged as a separate install option,
271 available by clicking the **Customize** button on the **Installation Type**
272 step of the installer as described above.
273
274 .. image:: mac_installer_09_custom_install_free_threaded.png
275
276 If the box next to the **Free-threaded Python** package name is checked,
277 a separate :file:`PythonT.framework` will also be installed
278 alongside the normal :file:`Python.framework` in :file:`/Library/Frameworks`.
279 This configuration allows a free-threaded Python |version| build to co-exist
280 on your system with a traditional (GIL only) Python |version| build with
281 minimal risk while installing or testing. This installation layout is itself
282 experimental and is subject to change in future releases.
283
284 Known cautions and limitations:
285
286 - The **UNIX command-line tools** package, which is selected by default,
287 will install links in :file:`/usr/local/bin` for |python_x_dot_y_t_literal|,
288 the free-threaded interpreter, and |python_x_dot_y_t_literal_config|,
289 a configuration utility which may be useful for package builders.
290 Since :file:`/usr/local/bin` is typically included in your shell ``PATH``,
291 in most cases no changes to your ``PATH`` environment variables should
292 be needed to use |python_x_dot_y_t_literal|.
293
294 - For this release, the **Shell profile updater** package and the
295 :file:`Update Shell Profile.command` in |applications_python_version_literal|
296 do not support the free-threaded package.
297
298 - The free-threaded build and the traditional build have separate search
299 paths and separate :file:`site-packages` directories so, by default,
300 if you need a package available in both builds, it may need to be installed in both.
301 The free-threaded package will install a separate instance of :program:`pip` for use
302 with |python_x_dot_y_t_literal|.
303
304 - To install a package using :command:`pip` without a :command:`venv`:
305
306 .. parsed-literal::
307
308 python\ |version|\ t -m pip install <package_name>
309
310 - When working with multiple Python environments, it is usually safest and easiest
311 to :ref:`create and use virtual environments <tut-venv>`.
312 This can avoid possible command name conflicts and confusion about which Python is in use:
313
314 .. parsed-literal::
315
316 python\ |version|\ t -m venv <venv_name>
317
318
319 then :command:`activate`.
320
321 - To run a free-threaded version of IDLE:
322
323 .. parsed-literal::
324
325 python\ |version|\ t -m idlelib
326
327
328 - The interpreters in both builds respond to the same
329 :ref:`PYTHON environment variables <using-on-envvars>`
330 which may have unexpected results, for example, if you have ``PYTHONPATH``
331 set in a shell profile. If necessary, there are
332 :ref:`command line options <using-on-interface-options>` like ``-E``
333 to ignore these environment variables.
334
335 - The free-threaded build links to the third-party shared libraries,
336 such as ``OpenSSL`` and ``Tk``, installed in the traditional framework.
337 This means that both builds also share one set of trust certificates
338 as installed by the :command:`Install Certificates.command` script,
339 thus it only needs to be run once.
340
341 - If you cannot depend on the link in ``/usr/local/bin`` pointing to the
342 ``python.org`` free-threaded |python_x_dot_y_t_literal| (for example, if you want
343 to install your own version there or some other distribution does),
344 you can explicitly set your shell ``PATH`` environment variable to
345 include the ``PythonT`` framework ``bin`` directory:
346
347 .. parsed-literal::
348
349 export PATH="/Library/Frameworks/PythonT.framework/Versions/\ |version|\ /bin":"$PATH"
350
351 The traditional framework installation by default does something similar,
352 except for :file:`Python.framework`. Be aware that having both framework ``bin``
353 directories in ``PATH`` can lead to confusion if there are duplicate names
354 like |python_x_dot_y_literal| in both; which one is actually used depends on the order
355 they appear in ``PATH``. The ``which python3.x`` or ``which python3.xt``
356 commands can show which path is being used. Using virtual environments
357 can help avoid such ambiguities. Another option might be to create
358 a shell :command:`alias` to the desired interpreter, like:
359
360 .. parsed-literal::
361
362 alias py\ |version|\ ="/Library/Frameworks/Python.framework/Versions/\ |version|\ /bin/python\ |version|\ "
363 alias py\ |version|\ t="/Library/Frameworks/PythonT.framework/Versions/\ |version|\ /bin/python\ |version|\ t"
364
365 Installing using the command line
366 ---------------------------------
367
368 If you want to use automation to install the ``python.org`` installer package
369 (rather than by using the familiar macOS :program:`Installer` GUI app),
370 the macOS command line :command:`installer` utility lets you select non-default
371 options, too. If you are not familiar with :command:`installer`, it can be
372 somewhat cryptic (see :command:`man installer` for more information).
373 As an example, the following shell snippet shows one way to do it,
374 using the |x_dot_y_b2_literal| release and selecting the free-threaded interpreter
375 option:
376
377 .. parsed-literal::
378
379 RELEASE="python-\ |version|\ 0b2-macos11.pkg"
380
381 # download installer pkg
382 curl -O \https://www.python.org/ftp/python/\ |version|\ .0/${RELEASE}
383
384 # create installer choicechanges to customize the install:
385 # enable the PythonTFramework-\ |version|\ package
386 # while accepting the other defaults (install all other packages)
387 cat > ./choicechanges.plist <<EOF
388 <?xml version="1.0" encoding="UTF-8"?>
389 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "\http://www.apple.com/DTDs/PropertyList-1.0.dtd">
390 <plist version="1.0">
391 <array>
392 <dict>
393 <key>attributeSetting</key>
394 <integer>1</integer>
395 <key>choiceAttribute</key>
396 <string>selected</string>
397 <key>choiceIdentifier</key>
398 <string>org.python.Python.PythonTFramework-\ |version|\ </string>
399 </dict>
400 </array>
401 </plist>
402 EOF
403
404 sudo installer -pkg ./${RELEASE} -applyChoiceChangesXML ./choicechanges.plist -target /
405
406
407 You can then test that both installer builds are now available with something like:
408
409 .. parsed-literal::
410
411 $ # test that the free-threaded interpreter was installed if the Unix Command Tools package was enabled
412 $ /usr/local/bin/python\ |version|\ t -VV
413 Python \ |version|\ .0b2 experimental free-threading build (v\ |version|\ .0b2:3a83b172af, Jun 5 2024, 12:57:31) [Clang 15.0.0 (clang-1500.3.9.4)]
414 $ # and the traditional interpreter
415 $ /usr/local/bin/python\ |version|\ -VV
416 Python \ |version|\ .0b2 (v\ |version|\ .0b2:3a83b172af, Jun 5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]
417 $ # test that they are also available without the prefix if /usr/local/bin is on $PATH
418 $ python\ |version|\ t -VV
419 Python \ |version|\ .0b2 experimental free-threading build (v\ |version|\ .0b2:3a83b172af, Jun 5 2024, 12:57:31) [Clang 15.0.0 (clang-1500.3.9.4)]
420 $ python\ |version|\ -VV
421 Python \ |version|\ .0b2 (v\ |version|\ .0b2:3a83b172af, Jun 5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]
422
423 .. note::
424
425 Current ``python.org`` installers only install to fixed locations like
426 :file:`/Library/Frameworks/`, :file:`/Applications`, and :file:`/usr/local/bin`.
427 You cannot use the :command:`installer` ``-domain`` option to install to
428 other locations.
429
430 .. _distributing-python-applications-on-the-mac:
431
432 Distributing Python Applications
433 --------------------------------
434
435 A range of tools exist for converting your Python code into a standalone
436 distributable application:
437
438 * :pypi:`py2app`: Supports creating macOS ``.app``
439 bundles from a Python project.
440
441 * `Briefcase <https://briefcase.readthedocs.io>`_: Part of the `BeeWare Project
442 <https://beeware.org>`_; a cross-platform packaging tool that supports
443 creation of ``.app`` bundles on macOS, as well as managing signing and
444 notarization.
445
446 * `PyInstaller <https://pyinstaller.org/>`_: A cross-platform packaging tool that creates
447 a single file or folder as a distributable artifact.
448
449 App Store Compliance
450 --------------------
451
452 Apps submitted for distribution through the macOS App Store must pass Apple's
453 app review process. This process includes a set of automated validation rules
454 that inspect the submitted application bundle for problematic code.
455
456 The Python standard library contains some code that is known to violate these
457 automated rules. While these violations appear to be false positives, Apple's
458 review rules cannot be challenged. Therefore, it is necessary to modify the
459 Python standard library for an app to pass App Store review.
460
461 The Python source tree contains
462 :source:`a patch file <Mac/Resources/app-store-compliance.patch>` that will remove
463 all code that is known to cause issues with the App Store review process. This
464 patch is applied automatically when CPython is configured with the
465 :option:`--with-app-store-compliance` option.
466
467 This patch is not normally required to use CPython on a Mac; nor is it required
468 if you are distributing an app *outside* the macOS App Store. It is *only*
469 required if you are using the macOS App Store as a distribution channel.
470
471 Other Resources
472 ===============
473
474 The `python.org Help page <https://www.python.org/about/help/>`_ has links to many useful resources.
475 The `Pythonmac-SIG mailing list <https://www.python.org/community/sigs/current/pythonmac-sig/>`_
476 is another support resource specifically for Python users and developers on the Mac.