Tutorial Python UV 2026: Curso Rápido e Projeto

Programação & Código

“`html

Apresentamos o UV, um gerenciador de pacotes Python extremamente rápido que foi projetado para simplificar a gestão de dependências, ambientes e a execução de projetos Python. Independentemente do seu nível de experiência, o UV pode acelerar seu fluxo de trabalho ao otimizar o gerenciamento de pacotes e garantir a consistência dos seus ambientes de desenvolvimento.

Este artigo explora o que é o UV e demonstra como utilizá-lo para configurar projetos, instalar dependências e executar scripts Python com facilidade. Para facilitar o aprendizado, apresentamos a seguinte agenda:

  • Entendimento aprofundado sobre o que é o UV.
  • Instalação do UV.
  • Configuração de um projeto Python com UV.
  • Gerenciamento de dependências usando UV.
  • Execução de scripts Python com UV.
  • Exemplo prático: Projeto de Web Scraper.
  • Exemplo prático: Projeto de API Data Fetcher.
  • Exploração dos comandos básicos e suas opções.

O que é o UV e Gestão de Versões Python

O UV é uma ferramenta abrangente para gerenciar ambientes, dependências e projetos Python. Ele visa otimizar todo o fluxo de trabalho, desde a instalação e gerenciamento de diferentes versões do Python até a execução de scripts e a construção de projetos.

Uma das funcionalidades centrais do UV é o gerenciamento de versões do Python no seu sistema. Isso é crucial quando você precisa alternar entre diferentes versões (como Python 3.8 e 3.9) para projetos distintos.

Instalando e Gerenciando Versões Python com UV

Para começar a gerenciar as versões do Python, você pode instalá-las utilizando o UV. O comando básico para instalação é:

uv python install [versão]

Para verificar quais versões do Python estão disponíveis para instalação, use:

uv python list

Este comando exibirá todas as versões disponíveis e as que já estão instaladas no seu sistema. Se você não tiver certeza de qual versão está instalada, pode verificar rapidamente:

uv python find

Para garantir que um projeto utilize uma versão específica do Python consistentemente, você pode “fixar” essa versão:

uv python pin [versão]

Caso deseje remover uma versão do Python que não está mais em uso:

uv python uninstall [versão]

O gerenciamento de versões do Python pelo UV assegura que você use a versão correta para cada projeto, evitando problemas de compatibilidade.

Executando Scripts Python com UV

O UV também facilita a execução e o gerenciamento de scripts Python independentes. Isso é ideal para scripts de arquivo único, oferecendo uma maneira simples de executá-los sem a necessidade de configurar manualmente um ambiente virtual.

Para executar um script simples, como um arquivo chamado example.py contendo print("Hello world"), utilize:

uv run example.py

Gerenciamento de Dependências em Scripts

O UV permite adicionar ou remover dependências diretamente associadas a um script específico, garantindo que ele rode com as bibliotecas corretas:

  • Para adicionar uma dependência: uv add [nome_do_script]
  • Para remover uma dependência: uv remove [nome_do_script]

Esta funcionalidade de gerenciamento de scripts no UV é focada na simplicidade, tornando a execução e o gerenciamento de dependências para projetos menores muito mais fáceis. Para projetos maiores, o UV oferece comandos para sincronização de ambientes, gerenciamento de dependências e construção de projetos, frequentemente utilizando o arquivo padrão pyproject.toml.

Instalando o UV

Para começar a usar o UV, você precisa instalá-lo no seu sistema. Existem diversas maneiras de fazer isso:

Instalação Standalone (Mac OS/Linux)

Você pode usar o comando curl, ou wget se o curl não estiver disponível:

curl -lsSf https://astral.sh/uv/install.sh | sh

Para instalar uma versão específica (ex: 0.9):

curl -lsSf https://astral.sh/uv/install.sh | sh -s 0.9

Instalação no Windows (PowerShell)

Execute no PowerShell como administrador:

Set-ExecutionPolicy bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://astral.sh/uv/install.ps1'))

Instalação via Pip

Se você já tem o Python (versão maior que 3) instalado e o pip configurado:

pip install uv

Outras Opções de Instalação

  • Homebrew (Mac OS): brew install uv
  • MacPorts: sudo port install uv
  • Winget: Utilize o comando específico para Winget.
  • Scoop: scoop install main/uv
  • Docker: Puxe a imagem mais recente: docker pull astralsh/uv

Projeto Prático 1: Web Scraper com UV

Vamos simular a configuração de um web scraper usando as bibliotecas requests e beautifulsoup4, gerenciando o ambiente com o UV.

Configuração Inicial do Projeto

  1. Crie e navegue para o diretório do projeto:

    mkdir web_scraper_project

    cd web_scraper_project

  2. Inicialize o projeto UV:

    uv init example

Isso criará a estrutura básica, incluindo main.py e o arquivo de metadados do projeto, pyproject.toml.

Adicionando e Gerenciando Dependências

Adicione as dependências necessárias:

uv add requests beautifulsoup4

Internamente, o UV adiciona estas bibliotecas ao seu arquivo pyproject.toml e as baixa para o ambiente do projeto. Verificando o pyproject.toml, você verá beautifulsoup4 e requests listados como dependências.

Executando Comandos de Projeto

Você pode executar verificações de formatação e estilo usando ferramentas como ruff, se adicionada:

uv run check

Para garantir a reprodutibilidade exata das versões das dependências, utilize o comando de lock:

uv lock

Isso gera o arquivo uv.lock, que congela as versões exatas das dependências (incluindo as transitivas).

Em seguida, sincronize o ambiente local com as especificações do lock:

uv sync

O uv sync lê o pyproject.toml, garante que as dependências estejam instaladas (ou as remove se estiverem obsoletas), fazendo com que o ambiente local corresponda exatamente ao arquivo de bloqueio, semelhante ao npm install em outros ecossistemas.

Estrutura de Diretórios Criada pelo UV

A estrutura gerada inclui:

  • .venv: Contém o ambiente virtual com os pacotes instalados (como ruff).
  • Dentro de .venv/Scripts (ou similar): Arquivos como activate.bat (para ativar o ambiente) e python.exe.
  • pyproject.toml: Arquivo de configuração para gerenciar dependências e configurações do projeto.
  • .gitignore: Arquivo para ignorar diretórios como o ambiente virtual.

Estrutura do Código Python (web_scraper_project/main.py)

Para este exemplo, criamos um arquivo scraper.py para buscar dados de uma API:

uv add requests beautifulsoup4 (Se ainda não estiverem adicionadas)

Conteúdo de scraper.py:

import requests
from bs4 import BeautifulSoup

# 1. Buscar a página web
response = requests.get("https://example.com")

# 2. Parsear o conteúdo HTML
soup = BeautifulSoup(response.text, "html.parser")

# 3. Encontrar todas as tags H1
h1_tags = soup.find_all("h1")

# 4. Imprimir o texto de cada tag H1
for tag in h1_tags:
    print(tag.text)

Executando o script:

uv run scraper.py

A saída esperada é o conteúdo da tag H1 do site de exemplo: "Example Domain".

Congelando Requisitos

Para garantir que outros desenvolvedores possam replicar o ambiente, compile as dependências em um arquivo requirements.txt usando o UV com suporte a PEP 621:

uv pip compile --universal --output-file requirements.txt requirements.in

Isso exige que você primeiro crie o arquivo de origem requirements.in listando as dependências de nível superior (ex: requests).

Para sincronizar um ambiente com base neste arquivo congelado:

uv pip sync requirements.txt

Projeto Prático 2: API Data Fetcher com UV

Neste projeto, simulamos a obtenção de dados de um API público (JSONPlaceholder), processamos as informações e as salvamos em um arquivo CSV.

Configuração Inicial do Projeto de API

  1. Crie um novo diretório e navegue até ele:

    mkdir API_data_fetcher

    cd API_data_fetcher

  2. Inicialize o projeto UV:

    uv init

  3. Crie um ambiente virtual e ative-o:

    uv venv create

    uv venv activate

  4. Adicione a dependência necessária (requests):

    uv add requests

Arquivo de Execução (fetch_and_export.py)

Este script faz uma requisição GET para buscar dados de usuários do JSONPlaceholder e os salva em users.csv, incluindo Nome, Email e Cidade.

import requests
import csv

# URL do endpoint da API
URL = "https://jsonplaceholder.typicode.com/users"

if response.status_code == 200:
    users = response.json()

    with open("users.csv", "w", newline="") as csvfile:
        writer = csv.writer(csvfile)
        # Escreve o cabeçalho
        writer.writerow(["name", "email", "city"])

        # Itera sobre os dados e escreve as linhas
        for user in users:
            name = user.get("name")
            email = user.get("email")
            city = user.get("address", {}).get("city")
            writer.writerow([name, email, city])

    print("Data saved to users.csv file.")
else:
    print(f"Error retrieving data. Status code: {response.status_code}")

Executando o script com UV:

uv run fetch_and_export.py

O resultado é o arquivo users.csv populado com os dados extraídos da API, demonstrando a facilidade com que o UV gerencia as dependências necessárias para rodar o código em um ambiente isolado.

Comandos Básicos e Opções do UV

O UV oferece um conjunto robusto de comandos para gerenciar seu ambiente de desenvolvimento. Abaixo, exploramos alguns dos comandos centrais e suas opções:

Comandos Principais

  • uv auth: Gerencia autenticação para serviços (login, logout, token).
  • uv login: Faz login em um serviço.
  • uv logout: Faz logout de um serviço.
  • uv token: Exibe o token de autenticação de um serviço.
  • uv dir: Mostra o caminho para o diretório de credenciais.
  • uv run [comando/script]: Executa um comando ou script em um ambiente isolado gerenciado pelo UV.
  • uv init: Inicializa um novo projeto, configurando a estrutura de diretórios e criando arquivos como pyproject.toml.
  • uv add [dependência]: Adiciona dependências ao projeto.
  • uv remove [dependência]: Remove dependências do projeto (similar a pip uninstall).
  • uv version: Atualiza as versões das dependências do projeto.
  • uv sync: Sincroniza o ambiente para corresponder às dependências especificadas no arquivo de lock (semelhante a pip install -r requirements.txt).
  • uv lock: Cria ou atualiza o arquivo uv.lock, congelando as versões exatas das dependências.
  • uv export: Exporta o arquivo de lock para um formato alternativo.
  • uv tree: Exibe a árvore de dependências do projeto para visualização da estrutura.
  • uv format: Formata o código Python do projeto (semelhante ao AutoPEP8).
  • uv tool [ferramenta]: Instala e executa ferramentas de linha de comando fornecidas por pacotes Python (ex: uv tool pycows hello world).
  • uv python: Gerencia instalações de versões Python.
  • uv pip: Interface compatível com pip, mas com recursos avançados como resolução independente de plataforma.
  • uv venv: Cria e gerencia ambientes virtuais.
  • uv build: Constrói pacotes Python em distribuições de código-fonte e wheels.
  • uv publish: Envia distribuições para índices de pacotes Python (como PyPI).
  • uv cache: Gerencia o cache de dependências baixadas.
  • uv self: Gerencia o próprio executável do UV (atualização, verificação de versão).
  • uv help: Exibe a documentação para qualquer comando UV.

Opções Comuns de Linha de Comando

Diversas opções podem ser usadas com os comandos do UV para customizar seu comportamento:

  • --allow-insecure-host: Permite conexões com hosts inseguros, desabilitando a verificação SSL (usar com cautela).
  • --cache-dir: Especifica o diretório do cache para armazenar credenciais e dados.
  • --color [auto|always|never]: Controla o uso de cores na saída do terminal.
  • --config-file: Especifica um arquivo de configuração customizado.
  • --directory: Altera o diretório de trabalho antes de executar o comando.
  • --no-cache: Desabilita o uso do cache, optando por arquivos temporários.
  • --offline: Desabilita o acesso à rede, usando apenas dados em cache localmente.
  • --username / --password: Utilizado para fornecer credenciais para processos de autenticação.
  • --keyring-provider [disabled|subprocess]: Define como as credenciais devem ser buscadas (subprocess usa keyring, disabled o ignora).
  • --native-tls: Permite carregar certificados TLS nativamente das lojas de certificados do sistema operacional.
  • --no-config: Evita a descoberta de arquivos de configuração como .toml.
  • --no-python-downloads: Desabilita o download de versões do Python.
  • --quiet: Habilita um modo silencioso, sem saída de log no console.
  • --token: Usado para fornecer um token de autenticação para um serviço.
  • --verbose: Fornece uma saída detalhada e granular (pode ser complementado pela variável de ambiente RUSTY_LOG).

Perguntas Frequentes

  • O que é o principal objetivo da ferramenta UV em desenvolvimento Python?
    O objetivo principal é gerenciar dependências, ambientes e pacotes Python de forma eficiente e rápida, otimizando o fluxo de trabalho do desenvolvedor.
  • Como posso garantir que meu projeto use uma versão específica do Python com UV?
    Você pode usar o comando uv python pin [versão] para fixar a versão desejada para o projeto atual.
  • Qual a melhor forma de garantir a reprodutibilidade do ambiente para outros usuários?
    Utilize uv lock para gerar um arquivo uv.lock com versões exatas de todas as dependências e, em seguida, faça com que outros usuários executem uv sync.
  • É possível instalar o UV sem usar os scripts de shell nativos?
    Sim, é possível instalá-lo usando gerenciadores de pacotes como pip (pip install uv), Homebrew, ou através de containers Docker.

“`

© 2025

política de privacidadetermos de uso