Instale o uv no Mac

Como instalar o uv no Mac. Use o instalador oficial ou o Homebrew para configurar o uv, o gerenciador rápido de pacotes e projetos Python. Cobre a configuração do PATH para Zsh, instalação do Python, criação do seu primeiro projeto e gerenciamento de pacotes com o uv no macOS.

A ferramenta uv é um gerenciador de pacotes e projetos Python extremamente rápido da Astral, escrito em Rust. Ela substitui ferramentas separadas como pip, pyenv, virtualenv e pipx por um único programa que é 10-100x mais rápido. Veja uv para Python no Mac [EN] para uma comparação detalhada do uv com outras ferramentas Python.

Instalar o Python é uma das etapas para configurar seu Mac para desenvolvimento. Veja o guia de configuração de Mac para desenvolvedores [EN].

Antes de começar

Você vai precisar de um aplicativo de terminal para instalar o uv e executar comandos Python. A Apple inclui o terminal do Mac [EN], mas eu prefiro o Warp Terminal. O Warp é um aplicativo de terminal fácil de usar, com assistência de IA para ajudar você a aprender e lembrar comandos do terminal. Baixe o Warp Terminal agora; ele é GRÁTIS e vale a pena experimentar.

Primeiros passos para instalar o uv no Mac

Primeiro, verifique a versão do macOS [EN]. Se você está em uma versão antiga, atualize o macOS [EN] para a versão mais recente do macOS [EN].

Você também vai precisar do Xcode Command Line Tools [EN] antes de instalar o uv, a menos que já tenha instalado o Homebrew [EN], que instala o Xcode Command Line Tools para você. O Command Line Tools fornece utilitários Unix básicos que o uv exige. Verifique se ele está instalado:

$ xcode-select -p

Se você ver um caminho como /Library/Developer/CommandLineTools, está pronto para continuar. Caso contrário, instale-o:

$ xcode-select --install

Siga as instruções para concluir a instalação. Veja Xcode Command Line Tools [EN] se precisar de mais detalhes.

Escolha um método de instalação

Você pode instalar o uv de duas formas no Mac: Homebrew [EN] ou o instalador curl oficial. Use o Homebrew se você já gerencia a maioria das ferramentas de desenvolvedor com brew e prefere um único gerenciador de pacotes para tudo. Veja Brew Install uv [EN] para o guia completo do Homebrew. Use o instalador oficial se você quer a versão mais recente e a capacidade de autoatualização integrada. A Astral, a desenvolvedora, recomenda instalar o uv no Mac com o script de instalação oficial.

Instale o uv com o instalador oficial

Não é necessário instalar o Homebrew nem o Python antes de instalar o uv com o instalador oficial. Ele cuida de tudo.

Execute este comando no seu terminal:

$ curl -LsSf https://astral.sh/uv/install.sh | sh

O comando curl baixa o script de instalação da Astral e o redireciona para o sh para execução. O instalador realiza três ações:

Instala os binários uv e uvx em ~/.local/bin
Modifica o seu arquivo de configuração do shell (~/.zshenv por padrão) para adicionar ~/.local/bin ao seu PATH
Cria um arquivo env em $HOME/.local/bin/env para ativar o uv na sessão atual

O instalador não exige privilégios de administrador nem sudo.

Depois que o instalador termina, você pode ativar o uv na sessão atual do terminal sem abrir uma nova janela:

$ source $HOME/.local/bin/env

O instalador cria esse arquivo env como um atalho para carregar o uv no seu PATH. Como alternativa, abra uma nova janela de terminal, que lê a configuração atualizada do shell automaticamente.

Veja as opções do instalador

Se você quer ver quais opções estão disponíveis antes de executar o instalador, use a flag de ajuda:

$ curl -LsSf https://astral.sh/uv/install.sh | sh -s -- --help

Mude o diretório de instalação

Por padrão, o uv instala em ~/.local/bin. Para mudar o local de instalação, defina a variável de ambiente UV_INSTALL_DIR:

$ curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR="/custom/path" sh

Eu não recomendo mudar o local de instalação, pois isso dificulta a manutenção.

Desative a modificação automática do PATH

O instalador modifica seu arquivo ~/.zshenv automaticamente. Se você prefere configurar o PATH por conta própria, desative o comportamento automático:

$ curl -LsSf https://astral.sh/uv/install.sh | env INSTALLER_NO_MODIFY_PATH=1 sh

Depois, defina o PATH manualmente, como descrito a seguir.

Instale o uv com Homebrew

Se você já usa o Homebrew, pode instalar o uv com um único comando:

$ brew install uv

Veja Brew Install uv [EN] para o guia completo de instalação com Homebrew, incluindo como o uv via Homebrew difere do instalador oficial e como atualizar com segurança.

Escolha o Homebrew se quiser o uv gerenciado junto com seus outros pacotes do Homebrew. Escolha o instalador oficial se quiser a versão mais recente imediatamente e a capacidade de autoatualização.

Configure o PATH para o uv no Mac

O PATH é uma variável de ambiente que diz ao shell onde encontrar programas. Depois de instalar o uv, seu PATH precisa incluir o diretório que contém o binário do uv para que você consiga executar uv de qualquer local.

Configuração automática do PATH

Se você usou o instalador oficial sem desativar a modificação do PATH, o instalador adicionou esta linha ao seu arquivo ~/.zshenv:

export PATH="$HOME/.local/bin:$PATH"

O arquivo ~/.zshenv é executado para todas as sessões do Zsh (tanto shells de login quanto shells interativos), então o uv ficará disponível em todo lugar. Isso funciona automaticamente para novas janelas de terminal.

Escolha um arquivo de configuração do shell

No macOS, o Zsh lê vários arquivos de configuração em uma ordem específica:

~/.zshenv é executado para toda sessão do shell (alvo padrão do instalador)
~/.zprofile é executado para shells de login (o que um aplicativo de terminal abre por padrão)
~/.zshrc é executado para shells interativos

Muitos desenvolvedores preferem definir o PATH em ~/.zprofile em vez de ~/.zshenv. As duas abordagens funcionam. Veja .zshrc ou .zprofile [EN] para uma explicação completa da diferença. O importante é que ~/.local/bin apareça no seu PATH.

Configure o PATH manualmente

Se você desativou a modificação automática do PATH ou instalou o uv com Homebrew, adicione a entrada do PATH você mesmo. Veja Configuração do shell [EN] para mais detalhes sobre como editar arquivos de configuração do shell.

Adicione esta linha ao final do arquivo:

export PATH="$HOME/.local/bin:$PATH"

Salve o arquivo e aplique as mudanças:

$ source ~/.zprofile

O comando source relê o arquivo de configuração na sessão atual. Como alternativa, abra uma nova janela de terminal.

Use uv tool update-shell

A ferramenta uv fornece um comando integrado para configurar seu PATH, como alternativa à edição manual do arquivo de configuração.

$ uv tool update-shell

Isso adiciona ~/.local/bin ao seu arquivo ~/.zshenv. É a mesma entrada de PATH que o instalador oficial cria automaticamente. Use esse comando se precisar reparar uma entrada de PATH ausente.

Nota sobre PATH para Apple Silicon vs Intel

Se você instalou o uv com Homebrew, a localização do binário depende do processador do seu Mac. Para o instalador curl oficial, o caminho é sempre ~/.local/bin, independentemente do processador.

No Apple Silicon (série M), o Homebrew instala em /opt/homebrew/bin:

export PATH="/opt/homebrew/bin:$PATH"

Em Macs Intel, o Homebrew usa /usr/local/bin:

export PATH="/usr/local/bin:$PATH"

A maioria dos Macs vendidos desde o final de 2020 usa Apple Silicon. Se os comandos do Homebrew já funcionam no seu terminal, o caminho correto já está definido.

Verifique o PATH

Depois de configurar o PATH, confirme que ele contém o diretório do binário do uv:

$ echo $PATH

Você deve ver ~/.local/bin (ou o diretório bin do Homebrew) na saída. O diretório mais à esquerda no PATH tem precedência sobre os diretórios à direita.

Verifique a instalação do uv

Confirme que o uv está instalado e acessível:

$ uv --version
uv 0.7.2

Você deve ver um número de versão (a sua pode ser mais recente). Se em vez disso você ver zsh: command not found: uv, consulte Command not found: uv [EN] para passos de solução de problemas.

Instale o Python com o uv

Um dos principais recursos do uv é a capacidade de instalar e gerenciar versões do Python. Essas instalações de Python são separadas do Python do sistema [EN] (instalado com o Xcode Command Line Tools) e de qualquer Python do Homebrew.

Instale a versão estável mais recente do Python:

$ uv python install

Para instalar uma versão específica:

$ uv python install 3.12

Você não deve tentar atualizar nem remover o Python do sistema instalado com o Xcode Command Line Tools. Apenas instale versões mais novas ao lado dele com o uv.

Verifique a instalação do Python

Verifique quais versões do Python o uv instalou:

$ uv python list --only-installed

Descubra qual versão do Python o uv vai usar por padrão:

$ uv python find

Verifique onde o uv guarda as instalações do Python:

$ uv python dir

A ferramenta uv mantém as versões do Python em ~/.local/share/uv/python/. Cada versão é autocontida e não interfere em outras instalações.

Inicie um projeto Python com o uv

Crie um novo projeto com uv init, que gera um arquivo pyproject.toml e configura a estrutura do projeto:

$ uv init myproject
$ cd myproject

Adicione uma dependência ao seu projeto:

$ uv add <package>

O comando uv add atualiza o arquivo pyproject.toml, resolve dependências e instala pacotes em um ambiente virtual criado automaticamente (.venv/ no diretório do projeto). Não é necessário executar python -m venv nem instalar virtualenv separadamente.

Execute um script dentro do ambiente do projeto:

$ uv run python script.py

O comando uv run garante que a versão correta do Python e todas as dependências do projeto estejam disponíveis.

Fixe uma versão do Python para um projeto

Defina uma versão específica do Python para um projeto:

$ uv python pin 3.12

Isso cria um arquivo .python-version no diretório do projeto. O uv vai usar essa versão para todos os comandos no projeto.

Use o uv como substituto do pip

Se você está seguindo um tutorial que usa comandos pip, o uv fornece uma interface compatível:

$ uv pip install requests
$ uv pip compile requirements.in -o requirements.txt

Esses comandos funcionam como pip, mas são significativamente mais rápidos.

Se você se deparou com error: externally-managed-environment ao executar pip install, o uv vai ajudar você a evitar o erro. Veja Fix: error: externally-managed-environment [EN].

Execute ferramentas com uvx

Execute ferramentas de linha de comando do Python (por exemplo, ruff) em ambientes efêmeros sem instalá-las permanentemente:

$ uvx ruff check .

Para instalar uma ferramenta permanentemente:

$ uv tool install ruff

O comando uvx é um atalho para uv tool run. Ele baixa e executa a ferramenta em um ambiente isolado que é limpo automaticamente. As ferramentas instaladas ficam em ~/.local/bin para que estejam disponíveis a partir da linha de comando.

Ative o autocompletar do shell para o uv

Configure o autocompletar com Tab para comandos do uv no Zsh (o shell padrão do macOS):

$ echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc

Reinicie o terminal ou execute source ~/.zshrc para ativar o autocompletar. O autocompletar com Tab facilita descobrir subcomandos e opções do uv.

Atualize o uv

Como você atualiza o uv depende de como você o instalou.

Se você instalou o uv com o instalador oficial, use o comando de autoatualização:

$ uv self update

Se você instalou o uv com Homebrew, use o comando de upgrade do Homebrew:

$ brew upgrade uv

Importante: não execute uv self update se você instalou o uv com Homebrew. Veja Brew Install uv [EN] para detalhes sobre como atualizar e gerenciar a instalação via Homebrew.

Desinstale o uv

Se você decidir remover o uv, primeiro limpe os dados armazenados (opcional):

$ uv cache clean
$ rm -r "$(uv python dir)"
$ rm -r "$(uv tool dir)"

Remova os binários do uv. Para o instalador oficial:

$ rm ~/.local/bin/uv ~/.local/bin/uvx

Para instalações via Homebrew:

$ brew uninstall uv

Se o instalador modificou seus arquivos de configuração do shell, edite ~/.zshenv ou ~/.zprofile para remover quaisquer entradas de PATH relacionadas ao uv.

Migre do Rye para o uv

Se você vem usando o Rye para gerenciamento de projetos Python, deve migrar para o uv. As duas ferramentas foram criadas por Charlie Marsh na Astral. O Rye agora está em modo de manutenção, e o uv é o substituto recomendado. Projetos Rye usam pyproject.toml, que o uv também suporta.

Para migrar um projeto Rye existente, navegue até o diretório do projeto e execute:

$ uv sync

Isso lê o pyproject.toml existente e instala todas as dependências. Use uv run no lugar de rye run para executar os comandos do projeto. Use uv add no lugar de rye add para adicionar novas dependências.

Solução de problemas do uv no Mac

Se você tiver problemas para instalar ou executar o uv, verifique estas questões comuns:

zsh: command not found: uv após a instalação: seu PATH não inclui ~/.local/bin nem o diretório bin do Homebrew. Veja Command not found: uv [EN] para correções passo a passo.
Misturar métodos de atualização: se você instalou o uv com Homebrew mas executou uv self update (ou vice-versa), pode ter instalações conflitantes. Desinstale um método e reinstale com o outro.
Configuração do shell não carregando: o macOS lê .zprofile para shells de login e .zshrc para shells interativos. Se as mudanças no PATH não estão fazendo efeito, talvez você tenha editado o arquivo errado. Veja .zshrc ou .zprofile [EN] para uma explicação.

Continue configurando seu Mac

Não perca o roteiro visual e checklist completo que mostra como configurar um Mac para desenvolvimento de software [EN], com todas as ferramentas e configurações essenciais que você talvez ainda não conheça.