Capítulo 3, Ambiente
pyenv: várias versões de Python na mesma máquina
Quando dois projetos pedem versões diferentes, trocar o Python do sistema não é uma opção. O pyenv resolve isso compilando versões isoladas na sua pasta de usuário.
Código deste capítulo: ambiente/cap03_pyenv.py
O problema que o pyenv resolve
Um projeto antigo roda no Python 3.12, um novo pede 3.14, e a biblioteca que você testa só funciona na 3.13. O pyenv instala todas elas lado a lado e escolhe a versão certa conforme a pasta em que você está, usando um arquivo .python-version.
brew install pyenv
xcode-select --install
Se as ferramentas de linha de comando da Apple já estiverem instaladas, o segundo comando avisa e não faz nada.
Ativar o pyenv no shell
No macOS e no Linux, o pyenv precisa interceptar o comando python. Adicione estas linhas ao ~/.zshrc (zsh) ou ao ~/.bashrc (bash) e abra um terminal novo:
export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
Instalar e escolher versões
pyenv install --list | grep -E "^\s*3\.1[234]\."
pyenv install 3.13
pyenv versions
pyenv global 3.13
Dentro da pasta de um projeto, pyenv local grava o arquivo .python-version, que deve ir para o Git:
cd meu-projeto
pyenv local 3.12
python --version
O pyenv escolhe a versão ativa seguindo uma ordem de prioridade:
| Prioridade | Mecanismo | Como definir |
|---|---|---|
| 1 (maior) | Sessão atual do terminal | pyenv shell 3.14 |
| 2 | Pasta do projeto | pyenv local 3.12 |
| 3 (menor) | Padrão do usuário | pyenv global 3.13 |
Para garantir no próprio código que a versão é a esperada, o script abaixo falha cedo e com uma mensagem clara:
import sys
assert sys.version_info >= (3, 12), "Este livro exige Python 3.12 ou superior"
print("versão ok")
versão ok
O custo de compilar
O pyenv compila cada versão a partir do código-fonte, o que leva alguns minutos e depende das bibliotecas de desenvolvimento instaladas. O uv, que eu apresento no capítulo 7, baixa binários prontos e instala a mesma versão em segundos. Eu uso pyenv quando preciso de uma compilação específica e uv no resto.