5. Usando Python em macOS

Este documento tem o objetivo de fornecer uma visão geral dos comportamentos específicos do macOS que você deve conhecer para começar a usar o Python em computadores Mac. O Python em um Mac com macOS é muito semelhante ao Python em outras plataformas derivadas do Unix, mas há algumas diferenças na instalação e alguns recursos.

Há várias maneiras de obter e instalar o Python para macOS. Versões pré-construídas das versões mais recentes do Python estão disponíveis em vários distribuidores. Grande parte deste documento descreve o uso dos Pythons fornecidos pela equipe de lançamento do CPython, disponíveis para download no site python.org. Consulte Alternative distributions para conhecer outras opções.

5.1. Usando Python para macOS do python.org

5.1.1. Etapas de instalação

For current Python versions (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 provided on the macOS downloads page. We recommend using the most recent supported Python version where possible. Current installers provide a universal2 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.15 Catalina on.

The downloaded file is a standard macOS installer package file (.pkg). File integrity information (such as checksum, size, and Sigstore signature) 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.

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

Ao clicar no botão Continuar, é exibido o Read Me desse instalador. Além de outras informações importantes, o Read Me documenta qual versão de Python será instalada e em quais versões do macOS ele é compatível. Talvez você precise rolar a tela para ler o arquivo inteiro. Por padrão, esse Read Me também será instalado em /Applications/Python 3.16/ e estará disponível para leitura a qualquer momento.

Ao clicar em Continuar, o instalador exibe a licença do Python e de outros softwares incluídos. Você precisará Concordar com os termos da licença antes de prosseguir para a próxima etapa. Esse arquivo de licença também será instalado e estará disponível para leitura a qualquer momento.

Após aceitar os termos da licença, a próxima etapa será a tela Tipo de instalação. Para a maioria dos usos, o conjunto padrão de operações de instalação é adequado.

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. For details of the optional free-threaded feature, which is installed by default, see Instalando binários com threads livres.

Em ambos os casos, clicar em Instalar iniciará o processo de instalação solicitando a permissão para instalar um novo software. É necessário um nome de usuário do macOS com privilégio de Administrador, pois o Python instalado estará disponível para todos os usuários do Mac.

Quando a instalação for concluída, a janela Resumo será exibida.

Clique duas vezes no ícone ou arquivo Install Certificates.command na janela /Applications/Python 3.16/ para concluir a instalação.

Isso abrirá uma janela temporária do console Terminal que usará o novo Python para baixar e instalar certificados raiz SSL para seu uso.

If Successfully installed certifi and update complete appear in the terminal window, the installation is complete. Close this terminal window and the installer window.

Uma instalação do padrão incluirá:

• Uma pasta Python 3.16 em sua pasta Applications. Aqui você encontra o IDLE, o ambiente de desenvolvimento que é parte das distribuições oficiais do Python; e o Python Launcher, que executa scripts Python quando são clicados duas vezes dentro do Finder .

• Uma framework /Library/Frameworks/Python.framework, que inclui o executável Python e suas bibliotecas. O instalador adiciona esse local ao seu path do console. Para desinstalar o Python, você pode remover esses três itens. É um link simbólico para o executável Python armazenado na pasta /usr/local/bin/.

Nota

As versões recentes do macOS incluem um comando python3 em /usr/bin/python3 que aponta para uma versão geralmente mais antiga e incompleta de Python fornecida por e para uso pelas ferramentas de desenvolvimento da Apple, Xcode ou o Command Line Tools for Xcode. Você nunca deve modificar ou tentar excluir essa instalação por ser controlada pela Apple e é usada por softwares da Apple ou de terceiros. Se você optar por instalar uma versão mais recente do Python a partir de python.org, você terá duas instalações diferentes, mas funcionais, de Python no computador que podem coexistir. As opções do instalador padrão devem garantir que o comando python3 seja usado em vez do python3 do sistema.

5.1.2. Como executar um script Python

Há duas maneiras de invocar o interpretador Python. Se você estiver familiarizado com o uso de um console Unix em terminal, você pode invocar python3.16 ou python3, opcionalmente seguido por uma ou mais opções da linha de comando (descritas em Linha de comando e ambiente). O tutorial de Python também tem uma seção útil sobre o uso interativo do Python a partir de um console.

Você também pode invocar o interpretador por um ambiente de desenvolvimento integrado (IDE). O IDLE — Editor e console Python é um editor e ambiente de desenvolvimento básico incluído com a distribuição padrão de Python. IDLE inclui um menu Ajuda que te permite acessar a documentação de Python. Se você for completamente iniciante em Python, você pode ler o tutorial de introdução na documentação.

Há muitos outros editores e IDEs disponíveis. Consulte Editores e IDEs para mais informações.

Para executar um script Python na janela do terminal, você pode invocar o interpretador com o nome do arquivo de script:

python3.16 meuscript.py

Para executar seu script a partir do Finder, você pode:

• Arrastá-lo para o Python Launcher.

• Selecione Python Launcher como a aplicação padrão para abrir seu script (ou qualquer script .py) na janela de informações Finder Info, e clique duas vezes nele. O Python Launcher tem várias preferências para controlar como o script é iniciado. Você pode arrastar opções para alterá-las por uma invocação, ou usar o menu Preferências para alterar configurações globalmente.

Saiba que executar o script diretamente do Finder pode produzir resultados diferentes daqueles obtidos em uma janela de terminal, pois o script não será executado no ambiente normal do console, incluindo qualquer configuração de variáveis de ambiente nos perfis do console. E, como em qualquer outro script ou programa, certifique-se do que está prestes a executar.

5.2. Alternative distributions

Além do instalador padrão do python.org para macOS, existem distribuições de terceiros para macOS que podem incluir funcionalidades adicionais. Algumas distribuições populares e seus recursos-chave são:

ActivePython

Instalador com compatibilidade multiplataforma, documentação

Anaconda

Módulos científicos populares (como numpy, scipy e pandas) e o gerenciador de pacotes conda.

Homebrew

Gerenciador de pacotes para macOS que inclui várias versões do Python e muitos pacotes Python de terceiros (incluindo numpy, scipy e pandas).

MacPorts

Outro gerenciador de pacotes para macOS, incluindo várias versões de Python e muitos pacotes Python de terceiros. Pode incluir versões pré-construídas do Python e muitos pacotes para versões mais antigas do macOS.

Note que distribuições podem não incluir versões mais recentes de Python ou de outras bibliotecas, e não são mantidas ou providas pela equipe do Python.

5.3. Installing additional Python packages

Consulte o Guia de Usuário para Empacotamento de Python para mais informações.

5.4. GUI programming

Existem várias opções para criar aplicações GUI no Mac com Python.

O kit de ferramentas GUI padrão de Python é o módulo tkinter, baseado no kit de ferramentas multiplataforma Tk (https://www.tcl.tk). Uma versão nativa do Tk para macOS está incluída no instalador.

O PyObjC é uma ligação em Python para o Objective-C/Cocoa da Apple framework. Informações sobre o PyObjC estão disponíveis em pyobjc.

Há vários kits de ferramentas GUI alternativas disponíveis para o macOS, incluindo:

• PySide: Ligações oficiais em Python ao kit de ferramentas Qt GUI .

• PyQt: Ligações alternativas em Python ao Qt.

• Kivy: Um kit de ferramentas GUI multiplataforma que dá suporte a plataformas de desktop e dispositivos móveis.

• Toga: Parte do BeeWare Project; dá suporte a aplicativos para desktop, dispositivos móveis, Web e console.

• wxPython: Um kit de ferramentas multiplataforma que dá suporte a sistemas operacionais desktop.

5.5. Advanced topics

5.5.1. Instalando binários com threads livres

Adicionado na versão 3.13.

Alterado na versão 3.15: Free-threading support is now installed by default.

The python.org Python for macOS installer package installs, by default, an additional build of Python 3.16 that supports free threading (running with the global interpreter lock disabled). Check the release page on python.org for possible updated information.

The free-threaded mode is working and continues to be improved, but there is some additional overhead in single-threaded workloads compared to the regular build. Additionally, third-party packages, in particular ones with an extension module, may not be ready for use in a free-threaded build, and will re-enable the GIL. As of Python 3.15, free-threading support is installed by default. It is packaged as a separate install option, which can be deselected 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 (as it is by default), a separate PythonT.framework will also be installed alongside the normal Python.framework in /Library/Frameworks. This configuration allows a free-threaded Python 3.16 build to co-exist on your system with a traditional (GIL only) Python 3.16 build with minimal risk while installing or testing. This installation layout may change in future releases.

Precauções e limitações conhecidas:

• The UNIX command-line tools package, which is selected by default, will install links in /usr/local/bin for python3.16t, the free-threaded interpreter, and python3.16t-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 variable should be needed to use python3.16t.

• Neste lançamento, o pacote Shell profile updater e o comando Update Shell Profile.command em /Applications/Python 3.16/ não dão suporte ao pacote com threads livres.

• A construção com threads livres e a compilação tradicional têm caminhos de pesquisa separados e diretórios site-packages separados, portanto, por padrão, se você precisar de um pacote disponível em ambas construções, talvez seja necessário instalá-lo em ambos. O pacote com threads livres instalará uma instância separada do pip para uso com o python3.16t.

  • Para instalar um pacote usando pip sem um venv:

    python3.16t -m pip install <package_name>

• Ao trabalhar com vários ambientes Python, geralmente é mais seguro e mais fácil criar e usar ambientes virtuais. Isso pode tanto evitar possíveis conflitos de comandos, quanto evitar a confusão sobre qual Python está sendo usado:

  python3.16t -m venv <venv_name>

  e, em seguida, activate.

• Para executar uma versão do IDLE com threads livres:

  python3.16t -m idlelib

• Os interpretadores em ambos as construções respondem às mesmas variáveis de ambiente PYTHON, o que pode gerar resultados inesperados, por exemplo, se você tiver PYTHONPATH definido em um perfil de console. Se necessário, há opções de linha de comando como -E para ignorar essas variáveis de ambiente.

• A construção com threads livres é ligada às bibliotecas compartilhadas de terceiros, como OpenSSL e Tk, instaladas no framework tradicional. Isso significa que ambas as compilações também compartilham um conjunto de certificados, como instalados pelo script Install Certificates.command, portanto, ele só precisa ser executado uma vez.

• Se você não puder depender do link em /usr/local/bin apontando para python3.16t com threads livres do python.org (por exemplo, se quiser instalar sua própria versão lá ou se alguma outra distribuição instalá-lo lá), você poderá definir explicitamente sua variável de ambiente de console PATH para incluir o diretório da framework PythonT bin:

  export PATH="/Library/Frameworks/PythonT.framework/Versions/3.16/bin":"$PATH"

  A instalação tradicional do framework por padrão faz algo semelhante, exceto pelo arquivo Python.framework. Observe que ter dois diretórios bin do framework em PATH pode gerar confusão se houver nomes duplicados, como python3.16, em ambos; qual deles é realmente usado depende da ordem em que aparecem em PATH. Os comandos which python3.x ou which python3.xt pode mostrar qual caminho está sendo usado. Usar ambientes virtuais pode ajudar a evitar essas ambiguidades. Outra opção pode ser criar um alias no console para o interpretador desejado, como:

  alias py3.16="/Library/Frameworks/Python.framework/Versions/3.16/bin/python3.16"
  alias py3.16t="/Library/Frameworks/PythonT.framework/Versions/3.16/bin/python3.16t"

5.5.2. Instalação usando a linha de comando

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.16.0b2 release and deselecting the free-threaded interpreter option:

RELEASE="python-3.160b2-macos11.pkg"

# download installer pkg
curl -O https://www.python.org/ftp/python/3.16.0/${RELEASE}

# create installer choicechanges to customize the install:
#    disable the PythonTFramework-3.16 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>0</integer>
                <key>choiceAttribute</key>
                <string>selected</string>
                <key>choiceIdentifier</key>
                <string>org.python.Python.PythonTFramework-3.16</string>
        </dict>
</array>
</plist>
EOF

sudo installer -pkg ./${RELEASE} -applyChoiceChangesXML ./choicechanges.plist -target /

After a default install, you can test that both builds are available with something like:

$ # test that the free-threaded interpreter was installed if the Unix Command Tools package was enabled
$ /usr/local/bin/python3.16t -VV
Python 3.16.0b2 free-threading build (v3.16.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.16 -VV
Python 3.16.0b2 (v3.16.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.16t -VV
Python 3.16.0b2 free-threading build (v3.16.0b2:3a83b172af, Jun  5 2024, 12:57:31) [Clang 15.0.0 (clang-1500.3.9.4)]
$ python3.16 -VV
Python 3.16.0b2 (v3.16.0b2:3a83b172af, Jun  5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]

Nota

Os instaladores atuais do python.org só instalam em locais fixos, como /Library/Frameworks/, /Applications e /usr/local/bin. Não é possível usar a opção -domain do installer para instalar em outros locais.

5.5.3. Distributing Python applications

Existe uma variedade de ferramentas para converter seu código Python em uma aplicação distribuível independente:

• py2app: Oferece suporte à criação de pacotes .app do macOS a partir de um projeto Python.

• Briefcase: Parte do BeeWare Project; uma ferramenta de empacotamento multiplataforma que permite criar bundles .app no macOS, além de gerenciar assinaturas digitais e a notarização.

• PyInstaller: Uma ferramenta de empacotamento multiplataforma que cria um único arquivo ou pasta como um artefato distribuível.

5.5.4. App Store compliance

As aplicações enviadas para distribuição pela macOS App Store devem passar pelo processo de revisão de aplicativos da Apple. Esse processo inclui um conjunto de regras de validação automatizadas que inspecionam o pacote de aplicativos enviado em busca de código problemático.

A biblioteca padrão do Python contém alguns códigos que violam essas regras automatizadas. Embora essas violações pareçam ser falsos positivos, as regras de revisão da Apple não podem ser contestadas. Portanto, é necessário modificar a biblioteca padrão do Python para que uma aplicação passe na revisão da App Store.

A árvore de fontes do Python contém um arquivo de patch que removerá todo o código que é conhecido por causar problemas no processo de revisão da App Store. Este patch é aplicado automaticamente quando o CPython é configurado com a opção --with-app-store-compliance.

Este patch normalmente não é necessário para usar o CPython em um Mac; nem é necessário se você estiver distribuindo uma aplicação fora da App Store do macOS. É necessário apenas se você estiver usando a App Store do macOS como canal de distribuição.

5.6. Outros recursos

A página de ajuda do python.org contém links para vários recursos úteis. A lista de discussão Pythonmac-SIG é outro recurso específico de suporte para usuários e desenvolvedores de Python no Mac.