Python Environment Understand

Vamos falar sobre o ambiente Python e os desafios de gerenciar versões e dependências em projetos. Se você já mexeu com Python, sabe como é o esquema inicial: instala o Python, cria seu projeto, puxa as dependências com o pip e joga tudo num requirements.txt. É o padrão de sempre, porem isso pode dar alguns pequenos problemas. Caos nas Versões e Dependências Versão do Python Digamos que você instalou o Python 3.9 globalmente, mas depois colocou o 3.12 no seu sistema. Qual versão seu projeto vai usar? Se escolher a errada pode dar alguns erros complicados. É tipo tentar encaixar uma peça de Lego em outro conjunto. Conflitos de Dependências Imagina que o Projeto A usa pandas 0.16. Aí você, instala o pandas 0.18.1 globalmente para outro projeto. Quando roda o Projeto A, ele quebra porque a versão antiga foi substituída. Isso pode causar: Incompatibilidade de API: Funções ou parâmetros que existiam no pandas 0.16 podem ter sumido ou mudado no 0.18.1. Erros: Tipo ImportError ou AttributeError por causa de mudanças internas no pacote. Dor de cabeça na manutenção: Gerenciar vários projetos com dependências diferentes no mesmo ambiente é pedir pra sofrer. Tentando Resolver com pyenv Mas isso tudo já foi resolvido pela própria comunidade. Temos como solução o pyenv — ele é um clássico para criar ambientes virtuais isolados para cada projeto. Com ele, você define uma versão específica do Python e instala as dependências listadas no requirements.txt. Isso já resolve nossos problemas tanto com as versões do Python quanto com as versões de dependência, então... tudo certo agora? É... ainda não. Temos mais um problema na questão das dependências. Mesmo que você use o requirements.txt para fixar as versões das dependências diretas, as dependências indiretas (aquelas que suas dependências precisam para funcionar) podem te ferrar. Por exemplo, o pandas depende de pacotes como: NumPy python-dateutil pytz A documentação do pandas informa versões mínimas para essas dependências, mas se outra biblioteca do seu projeto pedir uma versão diferente (tipo NumPy 0.3.4 vs. NumPy 0.6.4), é erro na certa. O requirements.txt trava as versões dos pacotes que você instala diretamente, mas não faz nada pras dependências das dependências. Então, se o pandas precisa de um NumPy específico e outra biblioteca pede uma versão diferente, o pyenv não vai te salvar. A Solução É aqui que entra o uv, uma ferramenta da Astral (os mesmos caras que criaram o Ruff). O uv é descrito como: "Um gerenciador de pacotes e projetos Python extremamente rápido, escrito em Rust." Rust aí sempre resolvendo problemas de outras linguagens... Ele vem pra substituir um monte de ferramentas que você já usa, tipo pip, pip-tools, pipx, poetry, pyenv, virtualenv e até twine. O uv é tão simples quanto o pip, mas alguns buffs a mais: Criar um projeto novo uv init # Initialized project `uv-test-python` Isso cria uma pasta com a seguinte estrutura: meu-projeto-python/ ├── .git/ ├── .gitignore ├── main.py ├── pyproject.toml ├── .python-version ├── README.md Adicionar dependências Quer usar o pandas? uv add pandas # Using CPython 3.13.3 # Creating virtual environment at: .venv # Resolved 7 packages in 572ms # Prepared 6 packages in 632ms # Installed 6 packages in 25ms # + numpy==2.2.6 # + pandas==2.2.3 # + python-dateutil==2.9.0.post0 # + pytz==2025.2 # + six==1.17.0 # + tzdata==2025.2 O uv cria um ambiente virtual (.venv), resolve todas as dependências (diretas e indiretas) e atualiza os arquivos. Arquivos gerados: meu-projeto-python/ ├── .git/ ├── .gitignore ├── main.py ├── pyproject.toml ├── .python-version ├── README.md ├── uv.lock ├── .venv/ .python-version: Define a versão do Python do projeto (ex.: 3.13.3). pyproject.toml: Contém informações do projeto, como nome, versão e dependências. uv.lock: Trava as versões exatas de todas as dependências, incluindo as indiretas, pra garantir que o projeto rode igual em qualquer máquina. Rodando o projeto: Pra executar seu código, é só usar: uv run main.py O uv ativa o ambiente virtual automaticamente e roda seu script com as dependências certas. Se você quiser garantir que o ambiente virtual tá 100% alinhado com o uv.lock, é só rodar: uv sync Isso instala ou atualiza todas as dependências conforme o lockfile, mantendo tudo consistente. Conclusão Ele elimina os conflitos de versões do Python e das dependências, trava até as dependências indiretas com o uv.lock e ainda é rápido já que é feito em Rust. Se você trabalha com vários projetos Python ou já sofreu com erros de compatibilidade, o uv é a ferramenta que vai te fazer economizar tempo e dor de cabeça. Fora que ele é fácil de usar e deixa seu fluxo de trabalho mais limpo e organizado. Valeu por ter lido até aqui! Testa o uv no seu próximo projeto e depois me conta como foi. Ref

May 20, 2025 - 21:40

Vamos falar sobre o ambiente Python e os desafios de gerenciar versões e dependências em projetos. Se você já mexeu com Python, sabe como é o esquema inicial: instala o Python, cria seu projeto, puxa as dependências com o pip e joga tudo num requirements.txt. É o padrão de sempre, porem isso pode dar alguns pequenos problemas.

Caos nas Versões e Dependências

Versão do Python

Digamos que você instalou o Python 3.9 globalmente, mas depois colocou o 3.12 no seu sistema. Qual versão seu projeto vai usar? Se escolher a errada pode dar alguns erros complicados. É tipo tentar encaixar uma peça de Lego em outro conjunto.

Conflitos de Dependências

Imagina que o Projeto A usa pandas 0.16. Aí você, instala o pandas 0.18.1 globalmente para outro projeto. Quando roda o Projeto A, ele quebra porque a versão antiga foi substituída. Isso pode causar:

Incompatibilidade de API: Funções ou parâmetros que existiam no pandas 0.16 podem ter sumido ou mudado no 0.18.1.
Erros: Tipo ImportError ou AttributeError por causa de mudanças internas no pacote.
Dor de cabeça na manutenção: Gerenciar vários projetos com dependências diferentes no mesmo ambiente é pedir pra sofrer.

Tentando Resolver com pyenv

Mas isso tudo já foi resolvido pela própria comunidade. Temos como solução o pyenv — ele é um clássico para criar ambientes virtuais isolados para cada projeto. Com ele, você define uma versão específica do Python e instala as dependências listadas no requirements.txt.

Isso já resolve nossos problemas tanto com as versões do Python quanto com as versões de dependência, então... tudo certo agora?

É... ainda não.

Temos mais um problema na questão das dependências.

Mesmo que você use o requirements.txt para fixar as versões das dependências diretas, as dependências indiretas (aquelas que suas dependências precisam para funcionar) podem te ferrar. Por exemplo, o pandas depende de pacotes como:

NumPy
python-dateutil
pytz

A documentação do pandas informa versões mínimas para essas dependências, mas se outra biblioteca do seu projeto pedir uma versão diferente (tipo NumPy 0.3.4 vs. NumPy 0.6.4), é erro na certa.

O requirements.txt trava as versões dos pacotes que você instala diretamente, mas não faz nada pras dependências das dependências. Então, se o pandas precisa de um NumPy específico e outra biblioteca pede uma versão diferente, o pyenv não vai te salvar.

A Solução

É aqui que entra o uv, uma ferramenta da Astral (os mesmos caras que criaram o Ruff). O uv é descrito como:

"Um gerenciador de pacotes e projetos Python extremamente rápido, escrito em Rust."

Rust aí sempre resolvendo problemas de outras linguagens...

Ele vem pra substituir um monte de ferramentas que você já usa, tipo pip, pip-tools, pipx, poetry, pyenv, virtualenv e até twine.

O uv é tão simples quanto o pip, mas alguns buffs a mais:

Criar um projeto novo

uv init 
# Initialized project `uv-test-python`

Isso cria uma pasta com a seguinte estrutura:

meu-projeto-python/
├── .git/
├── .gitignore
├── main.py
├── pyproject.toml
├── .python-version
├── README.md

Adicionar dependências

Quer usar o pandas?

uv add pandas
# Using CPython 3.13.3
# Creating virtual environment at: .venv
# Resolved 7 packages in 572ms
# Prepared 6 packages in 632ms
# Installed 6 packages in 25ms
#  + numpy==2.2.6
#  + pandas==2.2.3
#  + python-dateutil==2.9.0.post0
#  + pytz==2025.2
#  + six==1.17.0
#  + tzdata==2025.2

O uv cria um ambiente virtual (.venv), resolve todas as dependências (diretas e indiretas) e atualiza os arquivos.

Arquivos gerados:

meu-projeto-python/
├── .git/
├── .gitignore
├── main.py
├── pyproject.toml
├── .python-version
├── README.md
├── uv.lock
├── .venv/

.python-version: Define a versão do Python do projeto (ex.: 3.13.3).
pyproject.toml: Contém informações do projeto, como nome, versão e dependências.
uv.lock: Trava as versões exatas de todas as dependências, incluindo as indiretas, pra garantir que o projeto rode igual em qualquer máquina.

Rodando o projeto:

Pra executar seu código, é só usar:

uv run main.py

O uv ativa o ambiente virtual automaticamente e roda seu script com as dependências certas.

Se você quiser garantir que o ambiente virtual tá 100% alinhado com o uv.lock, é só rodar:

uv sync

Isso instala ou atualiza todas as dependências conforme o lockfile, mantendo tudo consistente.

Conclusão

Ele elimina os conflitos de versões do Python e das dependências, trava até as dependências indiretas com o uv.lock e ainda é rápido já que é feito em Rust. Se você trabalha com vários projetos Python ou já sofreu com erros de compatibilidade, o uv é a ferramenta que vai te fazer economizar tempo e dor de cabeça. Fora que ele é fácil de usar e deixa seu fluxo de trabalho mais limpo e organizado.

Valeu por ter lido até aqui! Testa o uv no seu próximo projeto e depois me conta como foi.