Debian Codegraph @

Doc/using/mac.rst

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