Conflitos de Dependência e Ambiente

Bugs de ambiente surgem de versões Python incompatíveis, lockfiles divergentes, pacotes mascarados no PYTHONPATH e instalações editáveis apontando para o checkout errado. Os sintomas incluem erros de importação, crashes de ABI e testes que passam localmente, mas falham em CI.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

python3 --version          # esperar 3.14.0 em ambientes alinhados com produção
which python3
uv sync                    # instalar de uv.lock
uv run pytest
python -c "import mypkg; print(mypkg.__file__)"

Quando usar isso:

ModuleNotFoundError para um pacote que você "acabou de instalar"
ImportError: DLL load failed / wheels binários incompatíveis
CI falha enquanto o laptop passa (ou vice-versa)
Dois projetos precisam de versões conflitantes da mesma biblioteca

Exemplo de Trabalho

# diagnose.sh - executar a partir da raiz do repositório
set -euo pipefail
 
echo "=== Python ==="
python3 --version
which python3
 
echo "=== Ambiente Virtual ==="
echo "${VIRTUAL_ENV:-não ativado}"
 
echo "=== Instalação do Lockfile ==="
uv sync --frozen
 
echo "=== Localização do Pacote ==="
uv run python -c "import orders; print(orders.__file__)"
 
echo "=== Distros Instaladas (topo) ==="
uv pip list | head -20
 
echo "=== pip check ==="
uv pip check

# pyproject.toml - fixar tempo de execução e isolar grupos
[project]
name = "orders"
requires-python = ">=3.14"
dependencies = ["fastapi>=0.115", "pydantic>=2"]
 
[dependency-groups]
dev = ["pytest>=8", "ruff>=0.9"]
 
[tool.uv]
dev-dependencies = ["pytest>=8", "ruff>=0.9"]

# verify_imports.py - smoke test de CI
import importlib
import sys
 
REQUIRED = ("fastapi", "pydantic", "orders")
 
def main() -> None:
    print("executable:", sys.executable)
    print("version:", sys.version.replace("\n", " "))
    for name in REQUIRED:
        mod = importlib.import_module(name)
        print(f"{name} -> {getattr(mod, '__file__', mod)}")
 
if __name__ == "__main__":
    main()

O que isso demonstra:

Versão e caminho impressos antes de depurar importações
uv sync --frozen falha se o lockfile estiver desatualizado com pyproject.toml
requires-python documenta o limite inferior do interpretador suportado
Script de smoke test de importação detecta o pacote errado no caminho cedo

Mergulho Profundo

Como Funciona

Ambientes virtuais isolam site-packages por projeto
Lockfiles fixam versões transitivas; pip install solto não faz isso
Wheels binários se ligam a tags ABI do Python (cp314 vs cp313)
Instalações editáveis (-e .) criam links simbólicos para o código fonte; cwd errado significa código errado

Checklist de Conflitos

Sinal	Causa Provável	Correção
Pacote antigo apesar da atualização	venv errado ativo	`deactivate`; ativar `.venv`
Duas versões em `pip list`	sistema + usuário	venv puro; `pip install --force-reinstall`
Wheel `cpython-312` em 3.14	wheel errado	regenerar lock no Python de destino
Importação de caminho inesperado	shadow do PYTHONPATH	remover; corrigir empacotamento
Poetry + uv misturados	duas ferramentas de lock	padronizar em uv 0.6+

Notas Python

# reproduzir CI localmente com container
docker run --rm -v "$PWD:/app" -w /app python:3.14.0-bookworm \
  bash -lc "pip install uv && uv sync --frozen && uv run pytest"

Armadilhas

pip install Global - polui o Python base; quebra outros projetos. Correção: venv por projeto; nunca instale dependências do aplicativo globalmente.
.venv Commitado - binários específicos da plataforma no git. Correção: gitignore; documentar uv sync no README.
Extras opcionais não instalados em CI - pip install . sem o extra [ml] faltando o torch. Correção: documentar extras; CI instala os grupos necessários.
cwd diferente no runner de teste do IDE - importa o módulo local json.py que sombreia. Correção: renomear sombras; layout de src.
Instalação editável desatualizada após renomear - nome antigo do pacote em cache. Correção: reinstalar editável; limpar *.egg-link.
Mistura Conda + pip - ABIs numpy/openssl quebradas. Correção: uma ferramenta por env; stack conda OU uv/pip.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
`uv` lock + sync	ambientes rápidos e reproduzíveis	organização exige apenas poetry (ponte com cuidado)
`pip-tools` compile	lojas existentes de `pip-tools`	projeto novo sem restrição
Dev apenas com Docker	paridade estrita com produção	iteração rápida no laptop necessária
Matrizes `tox`/`nox`	bibliotecas multi-versão	microsserviços de versão única

FAQs

Por que uv sync corrige "funciona na minha máquina"?

Todos instalam o mesmo grafo resolvido de uv.lock no mesmo ABI do Python. A derivação aparece como uma incompatibilidade de lock em vez de importações misteriosas.

A CI deve usar --frozen?

Sim em pipelines de release. Falha quando pyproject.toml muda sem atualizar o lockfile, prevenindo upgrades silenciosos.

Como depurar o caminho do módulo errado?

python -c "import m; print(m.__file__)" e comparar com o site-packages esperado ou o caminho editável de src/.

Dois projetos podem compartilhar um venv?

Evite. Pins conflitantes e sombreamento de importação retornam. Um venv por repositório ou use o workspace uv com membros explícitos.

E se as wheels CUDA do PyTorch diferirem por máquina?

Documente índices extras opcionais no README. Jobs apenas CPU da CI instalam o índice CPU; máquinas GPU instalam o extra específico da plataforma.

Como fixar o Python 3.14 no Docker?

Use python:3.14.0-bookworm (ou slim) e combine com requires-python em pyproject.toml.

O ruff precisa do mesmo venv?

Execute ruff 0.9+ via uv run ruff para que as regras e correções automáticas vejam os stubs de terceiros instalados de forma consistente.

Como corrigir falhas do pip check?

uv pip check relata pins incompatíveis. Regenerar o lock a partir de um venv limpo; remover overrides manuais de pip install no Dockerfile.

E quanto ao Python do sistema no macOS?

Use python3 de .venv após uv venv. Pythons Homebrew/sistema são bons como interpretadores base, não como alvos de instalação.

Como os grupos de dependência opcionais ajudam?

Mantenha pilhas pesadas de ML opcionais ([project.optional-dependencies]) para que os serviços de API não instalem PyTorch em cada imagem.

Posso deletar uv.lock e regenerar?

Sim ao atualizar versões principais deliberadamente. Commite o novo lock e execute a matriz completa de CI depois.

Como ocorrem conflitos entre IDE e CLI?

A IDE aponta para um interpretador diferente do terminal. Defina explicitamente o interpretador do workspace para .venv/bin/python.

Relacionados

Configuração e Ajustes - variáveis de ambiente vs pacotes
Layout src e Estrutura de Pacotes - instalar antes de testar
Cenários de Importação Circular - erros de importação que parecem dependências ausentes
Checklist de Auditoria de Código - lockfile e itens de auditoria
Ferramentas de Depuração - inspecionar sys.path em pdb

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

Conflitos de Dependência e Ambiente

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

python3 --version          # esperar 3.14.0 em ambientes alinhados com produção
which python3
uv sync                    # instalar de uv.lock
uv run pytest
python -c "import mypkg; print(mypkg.__file__)"

Quando usar isso:

ModuleNotFoundError para um pacote que você "acabou de instalar"
ImportError: DLL load failed / wheels binários incompatíveis
CI falha enquanto o laptop passa (ou vice-versa)
Dois projetos precisam de versões conflitantes da mesma biblioteca

Exemplo de Trabalho

# diagnose.sh - executar a partir da raiz do repositório
set -euo pipefail
 
echo "=== Python ==="
python3 --version
which python3
 
echo "=== Ambiente Virtual ==="
echo "${VIRTUAL_ENV:-não ativado}"
 
echo "=== Instalação do Lockfile ==="
uv sync --frozen
 
echo "=== Localização do Pacote ==="
uv run python -c "import orders; print(orders.__file__)"
 
echo "=== Distros Instaladas (topo) ==="
uv pip list | head -20
 
echo "=== pip check ==="
uv pip check

# pyproject.toml - fixar tempo de execução e isolar grupos
[project]
name = "orders"
requires-python = ">=3.14"
dependencies = ["fastapi>=0.115", "pydantic>=2"]
 
[dependency-groups]
dev = ["pytest>=8", "ruff>=0.9"]
 
[tool.uv]
dev-dependencies = ["pytest>=8", "ruff>=0.9"]

# verify_imports.py - smoke test de CI
import importlib
import sys
 
REQUIRED = ("fastapi", "pydantic", "orders")
 
def main() -> None:
    print("executable:", sys.executable)
    print("version:", sys.version.replace("\n", " "))
    for name in REQUIRED:
        mod = importlib.import_module(name)
        print(f"{name} -> {getattr(mod, '__file__', mod)}")
 
if __name__ == "__main__":
    main()

O que isso demonstra:

Versão e caminho impressos antes de depurar importações
uv sync --frozen falha se o lockfile estiver desatualizado com pyproject.toml
requires-python documenta o limite inferior do interpretador suportado
Script de smoke test de importação detecta o pacote errado no caminho cedo

Mergulho Profundo

Como Funciona

Ambientes virtuais isolam site-packages por projeto
Lockfiles fixam versões transitivas; pip install solto não faz isso
Wheels binários se ligam a tags ABI do Python (cp314 vs cp313)
Instalações editáveis (-e .) criam links simbólicos para o código fonte; cwd errado significa código errado

Checklist de Conflitos

Sinal	Causa Provável	Correção
Pacote antigo apesar da atualização	venv errado ativo	`deactivate`; ativar `.venv`
Duas versões em `pip list`	sistema + usuário	venv puro; `pip install --force-reinstall`
Wheel `cpython-312` em 3.14	wheel errado	regenerar lock no Python de destino
Importação de caminho inesperado	shadow do PYTHONPATH	remover; corrigir empacotamento
Poetry + uv misturados	duas ferramentas de lock	padronizar em uv 0.6+

Notas Python

# reproduzir CI localmente com container
docker run --rm -v "$PWD:/app" -w /app python:3.14.0-bookworm \
  bash -lc "pip install uv && uv sync --frozen && uv run pytest"

Armadilhas

pip install Global - polui o Python base; quebra outros projetos. Correção: venv por projeto; nunca instale dependências do aplicativo globalmente.
.venv Commitado - binários específicos da plataforma no git. Correção: gitignore; documentar uv sync no README.
Extras opcionais não instalados em CI - pip install . sem o extra [ml] faltando o torch. Correção: documentar extras; CI instala os grupos necessários.
cwd diferente no runner de teste do IDE - importa o módulo local json.py que sombreia. Correção: renomear sombras; layout de src.
Instalação editável desatualizada após renomear - nome antigo do pacote em cache. Correção: reinstalar editável; limpar *.egg-link.
Mistura Conda + pip - ABIs numpy/openssl quebradas. Correção: uma ferramenta por env; stack conda OU uv/pip.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
`uv` lock + sync	ambientes rápidos e reproduzíveis	organização exige apenas poetry (ponte com cuidado)
`pip-tools` compile	lojas existentes de `pip-tools`	projeto novo sem restrição
Dev apenas com Docker	paridade estrita com produção	iteração rápida no laptop necessária
Matrizes `tox`/`nox`	bibliotecas multi-versão	microsserviços de versão única

FAQs

Por que uv sync corrige "funciona na minha máquina"?

Todos instalam o mesmo grafo resolvido de uv.lock no mesmo ABI do Python. A derivação aparece como uma incompatibilidade de lock em vez de importações misteriosas.

A CI deve usar --frozen?

Sim em pipelines de release. Falha quando pyproject.toml muda sem atualizar o lockfile, prevenindo upgrades silenciosos.

Como depurar o caminho do módulo errado?

python -c "import m; print(m.__file__)" e comparar com o site-packages esperado ou o caminho editável de src/.

Dois projetos podem compartilhar um venv?

Evite. Pins conflitantes e sombreamento de importação retornam. Um venv por repositório ou use o workspace uv com membros explícitos.

E se as wheels CUDA do PyTorch diferirem por máquina?

Documente índices extras opcionais no README. Jobs apenas CPU da CI instalam o índice CPU; máquinas GPU instalam o extra específico da plataforma.

Como fixar o Python 3.14 no Docker?

Use python:3.14.0-bookworm (ou slim) e combine com requires-python em pyproject.toml.

O ruff precisa do mesmo venv?

Execute ruff 0.9+ via uv run ruff para que as regras e correções automáticas vejam os stubs de terceiros instalados de forma consistente.

Como corrigir falhas do pip check?

uv pip check relata pins incompatíveis. Regenerar o lock a partir de um venv limpo; remover overrides manuais de pip install no Dockerfile.

E quanto ao Python do sistema no macOS?

Use python3 de .venv após uv venv. Pythons Homebrew/sistema são bons como interpretadores base, não como alvos de instalação.

Como os grupos de dependência opcionais ajudam?

Mantenha pilhas pesadas de ML opcionais ([project.optional-dependencies]) para que os serviços de API não instalem PyTorch em cada imagem.

Posso deletar uv.lock e regenerar?

Sim ao atualizar versões principais deliberadamente. Commite o novo lock e execute a matriz completa de CI depois.

Como ocorrem conflitos entre IDE e CLI?

A IDE aponta para um interpretador diferente do terminal. Defina explicitamente o interpretador do workspace para .venv/bin/python.

Relacionados

Configuração e Ajustes - variáveis de ambiente vs pacotes
Layout src e Estrutura de Pacotes - instalar antes de testar
Cenários de Importação Circular - erros de importação que parecem dependências ausentes
Checklist de Auditoria de Código - lockfile e itens de auditoria
Ferramentas de Depuração - inspecionar sys.path em pdb

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

Conflitos de Dependência e Ambiente

Buscar na documentação

Conflitos de Dependência e Ambiente