Ambientes Virtuais: Guia Rápido

Um ambiente virtual isola as dependências do projeto do Python do sistema e de outros projetos. Crie um antes de instalar bibliotecas - é o primeiro passo em qualquer base de código Python real.

Receita

# uv (recomendado)
uv venv
source .venv/bin/activate
uv pip install httpx pydantic
 
# venv da biblioteca padrão
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

Quando usar isto:

Iniciando qualquer nova aplicação ou biblioteca
Reproduzindo CI localmente com dependências fixadas
Evitando a deriva de versão "funciona na minha máquina"
Executando ferramentas (ruff, mypy) sem instalações globais

Exemplo de Trabalho

# Criar projeto com uv
mkdir demo-app && cd demo-app
uv init --app
uv add fastapi uvicorn pydantic
 
# Executar usando o interpretador do projeto (nenhuma ativação manual necessária)
uv run python -c "import fastapi; print(fastapi.__version__)"
 
# Sincronizar do lockfile em um clone recém-criado
uv sync

# verify_env.py - execute com: uv run python verify_env.py
import sys
 
def main() -> None:
    prefix = sys.prefix
    in_venv = sys.prefix != sys.base_prefix
    print(f"prefix={prefix}")
    print(f"isolated={in_venv}")
    print(f"version={sys.version.split()[0]}")
 
if __name__ == "__main__":
    main()

O que isto demonstra:

uv venv / uv init cria .venv ao lado do projeto
uv add registra as dependências em pyproject.toml e no lockfile
uv run executa comandos dentro do ambiente do projeto
sys.prefix != sys.base_prefix confirma o isolamento

Mergulho Profundo

Como Funciona

venv copia ou vincula o interpretador Python base para .venv.
Shim de PATH - A ativação adiciona .venv/bin ao início do PATH para que python seja resolvido localmente.
site-packages - As wheels instaladas vão para .venv/lib/python3.14/site-packages.
uv - Toolchain baseada em Rust: resolvedor rápido, lockfile, uv sync, uv run.
PEP 668 - O Python do sistema em muitas distribuições Linux se marca como "gerenciado externamente" - venv é necessário.

Comparação de Ferramentas

Ferramenta	Ponto Forte
`uv`	Velocidade, lockfile, fluxo de trabalho do projeto
`venv`	Biblioteca padrão, sem instalação extra
`pip-tools`	Compilação legada de requirements.in
`poetry` / `pdm`	Gerenciamento completo de empacotamento + ambiente

Notas do Python

# Ativação no Windows
.venv\Scripts\activate
 
# Desativar
deactivate
 
# Qual python
which python
python -c "import sys; print(sys.executable)"

Armadilhas

Instalar globalmente - Quebra ferramentas do sistema operacional no Linux/macOS. Correção: Sempre use venv ou uv run.
Enviar .venv - Enorme e específico da plataforma. Correção: Gitignore .venv; envie pyproject.toml + lock.
Interpretador errado no IDE - Executa o Python do sistema sem dependências. Correção: Selecione .venv/bin/python no editor.
Shell de ativação desatualizado - Caminho antigo do venv após renomear. Correção: deactivate e reative.
Misturar pip e uv - Estado de lock confuso. Correção: Escolha um fluxo de trabalho por repositório (prefira uv).

Alternativas

Alternativa	Use Quando	Não Use Quando
`uv` projeto	Novas aplicações e bibliotecas	Air-gapped sem binário uv
`docker`	Paridade de implantação	Apenas verificação de sintaxe local
`pyenv`	Múltiplas versões do Python	Versão única é suficiente
`conda`	Pilha científica com binários	Serviço web puro

FAQs

Eu devo ativar o venv?

Com uv run, não. Para comandos python/pip simples, ative ou use o caminho completo .venv/bin/python.

O que vai em .gitignore?

.venv/, __pycache__/, .pytest_cache/, arquivos .env locais com segredos.

uv ou pip?

uv para novos projetos - instalações e lockfiles mais rápidos. pip dentro do venv está bom para scripts pequenos.

Como recrio um venv?

Exclua .venv, execute uv sync ou uv venv && uv pip install -r requirements.txt.

Posso nomear a pasta venv de outra forma?

Sim - .venv é uma convenção. Atualize o caminho do interpretador do IDE de acordo.

Como fixo o Python 3.14?

Use pyenv, uv python pin 3.14, ou matriz de CI python-version: "3.14".

O que é uv sync?

Instala dependências exatamente de uv.lock - clones e CI reproduzíveis.

Por que o erro de ambiente gerenciado externamente?

PEP 668 protege o Python do sistema. Crie um venv em vez de pip install globalmente.

Como instalo ferramentas de desenvolvimento?

uv add --dev ruff mypy pytest - mantém as ferramentas fora dos conjuntos de dependências de produção quando configurado.

venv inclui pip?

Sim, por padrão com python -m venv. uv gerencia instalações compatíveis com pip em seus ambientes.

Relacionado

Módulos, Imports e Pacotes - layout do pacote
uv - a toolchain rápida - fluxo de trabalho completo do uv
pyproject.toml explicado - metadados de dependência
gerenciando versões do Python - pyenv e pins

Versões da Pilha: Esta página foi escrita para Python 3.14.0 (3.14 estável, 3.13 de manutenção), 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+.

Ambientes Virtuais: Guia Rápido

Um ambiente virtual isola as dependências do projeto do Python do sistema e de outros projetos. Crie um antes de instalar bibliotecas - é o primeiro passo em qualquer base de código Python real.

Receita

# uv (recomendado)
uv venv
source .venv/bin/activate
uv pip install httpx pydantic
 
# venv da biblioteca padrão
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

Quando usar isto:

Iniciando qualquer nova aplicação ou biblioteca
Reproduzindo CI localmente com dependências fixadas
Evitando a deriva de versão "funciona na minha máquina"
Executando ferramentas (ruff, mypy) sem instalações globais

Exemplo de Trabalho

# Criar projeto com uv
mkdir demo-app && cd demo-app
uv init --app
uv add fastapi uvicorn pydantic
 
# Executar usando o interpretador do projeto (nenhuma ativação manual necessária)
uv run python -c "import fastapi; print(fastapi.__version__)"
 
# Sincronizar do lockfile em um clone recém-criado
uv sync

# verify_env.py - execute com: uv run python verify_env.py
import sys
 
def main() -> None:
    prefix = sys.prefix
    in_venv = sys.prefix != sys.base_prefix
    print(f"prefix={prefix}")
    print(f"isolated={in_venv}")
    print(f"version={sys.version.split()[0]}")
 
if __name__ == "__main__":
    main()

O que isto demonstra:

uv venv / uv init cria .venv ao lado do projeto
uv add registra as dependências em pyproject.toml e no lockfile
uv run executa comandos dentro do ambiente do projeto
sys.prefix != sys.base_prefix confirma o isolamento

Mergulho Profundo

Como Funciona

venv copia ou vincula o interpretador Python base para .venv.
Shim de PATH - A ativação adiciona .venv/bin ao início do PATH para que python seja resolvido localmente.
site-packages - As wheels instaladas vão para .venv/lib/python3.14/site-packages.
uv - Toolchain baseada em Rust: resolvedor rápido, lockfile, uv sync, uv run.
PEP 668 - O Python do sistema em muitas distribuições Linux se marca como "gerenciado externamente" - venv é necessário.

Comparação de Ferramentas

Ferramenta	Ponto Forte
`uv`	Velocidade, lockfile, fluxo de trabalho do projeto
`venv`	Biblioteca padrão, sem instalação extra
`pip-tools`	Compilação legada de requirements.in
`poetry` / `pdm`	Gerenciamento completo de empacotamento + ambiente

Notas do Python

# Ativação no Windows
.venv\Scripts\activate
 
# Desativar
deactivate
 
# Qual python
which python
python -c "import sys; print(sys.executable)"

Armadilhas

Instalar globalmente - Quebra ferramentas do sistema operacional no Linux/macOS. Correção: Sempre use venv ou uv run.
Enviar .venv - Enorme e específico da plataforma. Correção: Gitignore .venv; envie pyproject.toml + lock.
Interpretador errado no IDE - Executa o Python do sistema sem dependências. Correção: Selecione .venv/bin/python no editor.
Shell de ativação desatualizado - Caminho antigo do venv após renomear. Correção: deactivate e reative.
Misturar pip e uv - Estado de lock confuso. Correção: Escolha um fluxo de trabalho por repositório (prefira uv).

Alternativas

Alternativa	Use Quando	Não Use Quando
`uv` projeto	Novas aplicações e bibliotecas	Air-gapped sem binário uv
`docker`	Paridade de implantação	Apenas verificação de sintaxe local
`pyenv`	Múltiplas versões do Python	Versão única é suficiente
`conda`	Pilha científica com binários	Serviço web puro

FAQs

Eu devo ativar o venv?

Com uv run, não. Para comandos python/pip simples, ative ou use o caminho completo .venv/bin/python.

O que vai em .gitignore?

.venv/, __pycache__/, .pytest_cache/, arquivos .env locais com segredos.

uv ou pip?

uv para novos projetos - instalações e lockfiles mais rápidos. pip dentro do venv está bom para scripts pequenos.

Como recrio um venv?

Exclua .venv, execute uv sync ou uv venv && uv pip install -r requirements.txt.

Posso nomear a pasta venv de outra forma?

Sim - .venv é uma convenção. Atualize o caminho do interpretador do IDE de acordo.

Como fixo o Python 3.14?

Use pyenv, uv python pin 3.14, ou matriz de CI python-version: "3.14".

O que é uv sync?

Instala dependências exatamente de uv.lock - clones e CI reproduzíveis.

Por que o erro de ambiente gerenciado externamente?

PEP 668 protege o Python do sistema. Crie um venv em vez de pip install globalmente.

Como instalo ferramentas de desenvolvimento?

uv add --dev ruff mypy pytest - mantém as ferramentas fora dos conjuntos de dependências de produção quando configurado.

venv inclui pip?

Sim, por padrão com python -m venv. uv gerencia instalações compatíveis com pip em seus ambientes.

Relacionado

Módulos, Imports e Pacotes - layout do pacote
uv - a toolchain rápida - fluxo de trabalho completo do uv
pyproject.toml explicado - metadados de dependência
gerenciando versões do Python - pyenv e pins

Versões da Pilha: Esta página foi escrita para Python 3.14.0 (3.14 estável, 3.13 de manutenção), 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+.

Ambientes Virtuais: Guia Rápido

Buscar na documentação

Ambientes Virtuais: Guia Rápido