Empacotamento e Distribuição de Projetos Python com uv

15 Sep, 2026

Entendendo o Conceito

O uv é uma ferramenta escrita em Rust projetada para otimizar o gerenciamento de dependências e o empacotamento em projetos Python. O comando uv build executa a compilação do código-fonte do projeto para gerar arquivos distribuíveis padronizados: o Source Distribution (sdist, no formato .tar.gz) e o Binary Distribution (wheel, no formato .whl).

Esses arquivos gerados são o meio oficial para distribuir bibliotecas e aplicações. Após a geração, esses pacotes podem ser instalados localmente em outros ambientes de desenvolvimento ou publicados em repositórios remotos — como o PyPI (Python Package Index) ou servidores privados de pacotes —, permitindo que sejam instalados de maneira automatizada e padronizada.

Passo a Passo

O processo para construir e distribuir o pacote envolve a configuração dos metadados, a compilação com a definição do diretório de destino e a publicação no repositório desejado.

1. Configuração inicial do projeto O projeto deve possuir um arquivo pyproject.toml válido localizado no diretório raiz, contendo a declaração do sistema de construção ([build-system]) e os metadados do pacote.

2. Compilação padrão do pacote Execute o comando de compilação diretamente no diretório raiz do projeto. Por padrão, o compilador deposita os artefatos gerados em uma pasta chamada dist/.

uv build

3. Compilação com diretório de saída customizado Caso precise salvar as distribuições geradas em uma pasta diferente, utilize o parâmetro --out-dir informando o caminho do diretório alternativo.

uv build --out-dir build_artifacts/

4. Instalação e teste local do pacote Para testar a biblioteca localmente, aponte o instalador de dependências diretamente para o arquivo .whl gerado.

uv pip install build_artifacts/nome_do_pacote-0.1.0-py3-none-any.whl

5. Publicação em repositório público (PyPI) Para enviar as distribuições geradas para o PyPI, utilize o utilitário uv publish. Como o diretório padrão foi alterado nos passos anteriores, especifique o caminho dos artefatos explicitamente e forneça o token de autenticação gerado no PyPI.

uv publish --token seu_token_pypi build_artifacts/*

6. Publicação em repositório privado ou alternativo Se o destino da publicação for uma infraestrutura interna ou um ambiente de testes (como o GitLab Package Registry ou TestPyPI), use o parâmetro --publish-url para apontar para o endpoint de upload correto.

uv publish --publish-url https://test.pypi.org/legacy/ --token seu_token build_artifacts/*

Explicando o código

Abaixo estão detalhados os principais comandos e parâmetros utilizados para as fases de construção e entrega de pacotes.

• uv build: Comando responsável por invocar o backend de construção definido no projeto para criar os pacotes distribuíveis.
  • --out-dir: Especifica a pasta de destino para as distribuições compiladas, substituindo a pasta padrão dist/.
  • --wheel: Configura a compilação para gerar apenas o arquivo de distribuição binária (.whl).
  • --sdist: Configura a compilação para gerar apenas o arquivo de distribuição de código-fonte (.tar.gz).
• uv publish: Ferramenta para upload dos arquivos empacotados para um índice remoto de pacotes Python.
  • --publish-url: Define a URL exata de upload (endpoint de publicação) do repositório remoto desejado.
  • --token: Informa a chave de autenticação (API token) exigida para validar o upload de pacotes no servidor.
  • --index: Permite indicar o nome de um índice específico pré-configurado nas diretivas do arquivo pyproject.toml.

Observações

• O comando uv build executa por padrão sob isolamento de build, montando um ambiente virtual temporário onde instala os requisitos mínimos de construção.
• Ao configurar repositórios privados na seção [[tool.uv.index]] do arquivo pyproject.toml, o uv build pode tentar resolver o próprio backend de construção (como o setuptools ou hatchling) usando esse repositório privado. Se este repositório privado não mantiver cópias das ferramentas de build, o processo falhará. Nesses cenários, recomenda-se passar a URL de destino diretamente via parâmetro de linha de comando no uv publish ou usar o parâmetro --no-index durante a compilação para que o resolvedor use o ambiente local.
• Lembre-se de atualizar o número de versão do pacote no pyproject.toml antes de executar uma nova compilação e publicação, pois o PyPI e outros servidores rejeitam novos uploads para uma versão já existente.

Referências

1. GLASMACHER, Sarah. How to build a Python package with uv and install it locally. Disponível em: https://www.sarahglasmacher.com/how-to-build-python-package-uv/. Acesso em: 15 set. 2026.
2. ASTRAL. Building distributions | uv. Disponível em: https://docs.astral.sh/uv/concepts/projects/build/. Acesso em: 15 set. 2026.
3. ASTRAL. Building and publishing a package | uv. Disponível em: https://docs.astral.sh/uv/guides/package/. Acesso em: 15 set. 2026.
4. LINUX COMMAND LIBRARY. uv-build man. Disponível em: https://linuxcommandlibrary.com/man/uv-build. Acesso em: 15 set. 2026.
5. LINUX COMMAND LIBRARY. uv-publish man. Disponível em: https://linuxcommandlibrary.com/man/uv-publish. Acesso em: 15 set. 2026.
6. STACKOVERFLOW. How to replace a Twine upload with uv publish?. Disponível em: https://stackoverflow.com/questions/79826604/how-to-replace-a-twine-upload-with-uv-publish. Acesso em: 15 set. 2026.

#automation #distribution #packaging #pypi #python #uv