Gerenciando Versões do Python

Executar múltiplas versões do Python em uma única máquina permite que você desenvolva na versão mais recente, teste a compatibilidade retroativa e corresponda exatamente aos interpretadores de produção.

Receita

# uv (recommended)
uv python install 3.13 3.14
uv python pin 3.14
 
# pyenv (alternative)
pyenv install 3.14.0
pyenv local 3.14.0

Quando usar isso:

Testar contra Python 3.13 e 3.14 no mesmo repositório
Corresponder a uma versão de interpretador de produção localmente
Contribuir para bibliotecas com amplo suporte requires-python

Exemplo de Trabalho

# Install interpreters
uv python install 3.13 3.14
 
# Pin project to 3.14
cd myproject
uv python pin 3.14
cat .python-version   # 3.14
 
# Test on 3.13 without changing the pin
uv run --python 3.13 pytest
 
# Multi-version CI matrix (GitHub Actions excerpt)

strategy:
  matrix:
    python-version: ["3.13", "3.14"]
steps:
  - uses: actions/setup-python@v5
    with:
      python-version: ${{ matrix.python-version }}
  - run: pip install -e ".[dev]" && pytest

O que isso demonstra:

uv python install baixa interpretadores sem gerenciadores de pacotes do sistema
.python-version fixa o padrão para uma árvore de diretórios
uv run --python executa um único comando contra outra versão
Matrizes de CI verificam a compatibilidade entre as versões suportadas

Mergulho Profundo

Como Funciona

uv python armazena interpretadores em ~/.local/share/uv/python/ e cria links simbólicos sob demanda
pyenv compila ou baixa interpretadores para ~/.pyenv/versions/ e usa shims para python via PATH
requires-python em pyproject.toml declara o intervalo suportado
tox/nox automatizam execuções de teste multi-versão localmente e em CI

Ferramentas de Seleção de Versão

Ferramenta	Instalar	Fixar por projeto	Velocidade
uv python	`uv python install`	`.python-version`	Rápido
pyenv	`pyenv install`	`.python-version`	Moderado
deadsnakes PPA	`apt install python3.14`	Manual	Sistema
asdf	`asdf install python`	`.tool-versions`	Moderado

Notas do Python

# pyproject.toml - declare supported range
[project]
requires-python = ">=3.13"

# tox.ini for local multi-version testing
[tox]
envlist = py313,py314

Armadilhas

Python do Sistema para projetos - falha quando o SO atualiza o Python. Correção: sempre use um venv de projeto com um interpretador fixado.
.python-version não commitado - colegas de equipe usam versões diferentes. Correção: comite .python-version ou documente em pyproject.toml.
Testar apenas na versão mais recente - surpreende usuários em versões mais antigas. Correção: matriz de CI cobrindo o limite inferior de requires-python.
Falhas de compilação do pyenv no macOS - ferramentas de linha de comando do Xcode ausentes. Correção: xcode-select --install; ou use uv python install (binários pré-compilados).
Misturar pins do pyenv e uv - shims conflitantes. Correção: padronize em um único gerenciador de versão por projeto.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Docker por versão	Reprodução exata da produção	Iteração local rápida
Nix/devcontainers	Ambientes idênticos para toda a equipe	Aplicativos simples de versão única
Pacotes do sistema apenas	Imagens de implantação de servidor	Desenvolvimento local

FAQs

uv python vs pyenv - qual devo usar?

uv python é mais rápido (binários pré-compilados) e se integra com fluxos de trabalho uv. pyenv tem um ecossistema de plugins mais amplo. Novos projetos: uv.

Como verifico a versão ativa do Python?

python --version ou uv run python --version dentro de um projeto.

Posso executar código 3.14 em 3.13?

Somente se você evitar sintaxe e APIs exclusivas do 3.14. Teste explicitamente em 3.13.

Qual arquivo fixa a versão?

.python-version (uv/pyenv), pyproject.toml requires-python, ou .tool-versions (asdf).

Como atualizo a versão do Python do projeto?

Instale a nova versão, atualize .python-version, atualize requires-python, recrie o venv e execute os testes.

Preciso de várias versões para bibliotecas?

Sim. Bibliotecas devem testar contra todas as versões em requires-python.

Como o Python 3.14 free-threaded se encaixa?

Instale a variante 3.14t com uv para testes sem GIL. A maioria dos aplicativos ainda usa a compilação padrão.

A CI pode usar uv para instalar Python?

Sim: uv python install 3.14 no GitHub Actions sem setup-python.

E quanto ao Windows?

uv fornece binários para Windows. pyenv-win é o port do pyenv para Windows.

Como listo as versões instaladas?

uv python list ou pyenv versions.

Relacionados

uv - A Toolchain Rápida - gerenciamento integrado de versões
Fundamentos de Ambientes e Empacotamento - fundamentos de venv
tox / nox - automação de testes multi-versão
Melhores Práticas de Ambientes - política de versões

Versões do Stack: Esta página foi escrita para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.

Gerenciando Versões do Python

Receita

# uv (recommended)
uv python install 3.13 3.14
uv python pin 3.14
 
# pyenv (alternative)
pyenv install 3.14.0
pyenv local 3.14.0

Quando usar isso:

Testar contra Python 3.13 e 3.14 no mesmo repositório
Corresponder a uma versão de interpretador de produção localmente
Contribuir para bibliotecas com amplo suporte requires-python

Exemplo de Trabalho

# Install interpreters
uv python install 3.13 3.14
 
# Pin project to 3.14
cd myproject
uv python pin 3.14
cat .python-version   # 3.14
 
# Test on 3.13 without changing the pin
uv run --python 3.13 pytest
 
# Multi-version CI matrix (GitHub Actions excerpt)

strategy:
  matrix:
    python-version: ["3.13", "3.14"]
steps:
  - uses: actions/setup-python@v5
    with:
      python-version: ${{ matrix.python-version }}
  - run: pip install -e ".[dev]" && pytest

O que isso demonstra:

uv python install baixa interpretadores sem gerenciadores de pacotes do sistema
.python-version fixa o padrão para uma árvore de diretórios
uv run --python executa um único comando contra outra versão
Matrizes de CI verificam a compatibilidade entre as versões suportadas

Mergulho Profundo

Como Funciona

uv python armazena interpretadores em ~/.local/share/uv/python/ e cria links simbólicos sob demanda
pyenv compila ou baixa interpretadores para ~/.pyenv/versions/ e usa shims para python via PATH
requires-python em pyproject.toml declara o intervalo suportado
tox/nox automatizam execuções de teste multi-versão localmente e em CI

Ferramentas de Seleção de Versão

Ferramenta	Instalar	Fixar por projeto	Velocidade
uv python	`uv python install`	`.python-version`	Rápido
pyenv	`pyenv install`	`.python-version`	Moderado
deadsnakes PPA	`apt install python3.14`	Manual	Sistema
asdf	`asdf install python`	`.tool-versions`	Moderado

Notas do Python

# pyproject.toml - declare supported range
[project]
requires-python = ">=3.13"

# tox.ini for local multi-version testing
[tox]
envlist = py313,py314

Armadilhas

Python do Sistema para projetos - falha quando o SO atualiza o Python. Correção: sempre use um venv de projeto com um interpretador fixado.
.python-version não commitado - colegas de equipe usam versões diferentes. Correção: comite .python-version ou documente em pyproject.toml.
Testar apenas na versão mais recente - surpreende usuários em versões mais antigas. Correção: matriz de CI cobrindo o limite inferior de requires-python.
Falhas de compilação do pyenv no macOS - ferramentas de linha de comando do Xcode ausentes. Correção: xcode-select --install; ou use uv python install (binários pré-compilados).
Misturar pins do pyenv e uv - shims conflitantes. Correção: padronize em um único gerenciador de versão por projeto.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Docker por versão	Reprodução exata da produção	Iteração local rápida
Nix/devcontainers	Ambientes idênticos para toda a equipe	Aplicativos simples de versão única
Pacotes do sistema apenas	Imagens de implantação de servidor	Desenvolvimento local

FAQs

uv python vs pyenv - qual devo usar?

uv python é mais rápido (binários pré-compilados) e se integra com fluxos de trabalho uv. pyenv tem um ecossistema de plugins mais amplo. Novos projetos: uv.

Como verifico a versão ativa do Python?

python --version ou uv run python --version dentro de um projeto.

Posso executar código 3.14 em 3.13?

Somente se você evitar sintaxe e APIs exclusivas do 3.14. Teste explicitamente em 3.13.

Qual arquivo fixa a versão?

.python-version (uv/pyenv), pyproject.toml requires-python, ou .tool-versions (asdf).

Como atualizo a versão do Python do projeto?

Instale a nova versão, atualize .python-version, atualize requires-python, recrie o venv e execute os testes.

Preciso de várias versões para bibliotecas?

Sim. Bibliotecas devem testar contra todas as versões em requires-python.

Como o Python 3.14 free-threaded se encaixa?

Instale a variante 3.14t com uv para testes sem GIL. A maioria dos aplicativos ainda usa a compilação padrão.

A CI pode usar uv para instalar Python?

Sim: uv python install 3.14 no GitHub Actions sem setup-python.

E quanto ao Windows?

uv fornece binários para Windows. pyenv-win é o port do pyenv para Windows.

Como listo as versões instaladas?

uv python list ou pyenv versions.

Relacionados

uv - A Toolchain Rápida - gerenciamento integrado de versões
Fundamentos de Ambientes e Empacotamento - fundamentos de venv
tox / nox - automação de testes multi-versão
Melhores Práticas de Ambientes - política de versões

Versões do Stack: Esta página foi escrita para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.

Gerenciando Versões do Python

Buscar na documentação

Gerenciando Versões do Python