Python PIP

pip é o gerenciador de pacotes integrado do Python. Ele baixa pacotes do PyPI (o Python Package Index) e os instala para que você possa usar import no seu código. Se você tiver Python 3.4 ou superior, o pip já está incluído — não é necessária instalação separada.

Este capítulo cobre tudo o que você precisa para usar o pip com confiança: verificar a instalação, instalar e remover pacotes, fixar versões, exportar dependências e corrigir erros comuns.

Verificando sua instalação do pip

Abra um terminal e execute:

pip --version

Você verá uma saída semelhante a:

pip 24.0 from /usr/lib/python3/dist-packages/pip (python 3.12)

Se o comando não for encontrado, ou se você tiver várias versões do Python, use a forma python -m pip — ela garante que você está executando o pip para o interpretador Python desejado:

python -m pip --version

Atualizando o pip

O pip lança novas versões com frequência. Mantenha-o atualizado para evitar avisos do resolvedor:

python -m pip install --upgrade pip

Instalando pacotes

Instalação básica

pip install requests

O pip baixa requests e todas as suas dependências do PyPI e as instala no seu ambiente Python ativo. Após a instalação, você pode importar o pacote imediatamente.

Instalando uma versão específica

Fixe em uma versão exata quando a reprodutibilidade for importante:

pip install requests==2.31.0

Você também pode expressar intervalos de versão usando operadores de comparação:

pip install "requests>=2.28,<3.0"

Sempre coloque intervalos entre aspas no shell para evitar que < e > sejam interpretados como redirecionamentos.

Instalando a partir de um arquivo de requisitos

Um arquivo requirements.txt lista todos os pacotes que um projeto precisa, um por linha. Instale todos os pacotes do arquivo com um único comando:

pip install -r requirements.txt

Um requirements.txt típico tem este aspecto:

requests==2.31.0
flask>=3.0,<4.0
sqlalchemy

Instalando no modo editável

Quando você está desenvolvendo um pacote local e quer que as alterações entrem em vigor sem reinstalar, use a flag -e:

pip install -e .

Isso vincula o diretório do pacote diretamente ao ambiente em vez de copiar os arquivos.

Instalando apenas para o usuário atual

Se você não tiver permissão para escrever no diretório do Python do sistema e não estiver usando um ambiente virtual, adicione --user:

pip install --user requests

O pacote é instalado no seu diretório home (~/.local/ no Linux/macOS). Isso é uma alternativa — usar um ambiente virtual é quase sempre a melhor escolha.

Listando e inspecionando pacotes

Listar todos os pacotes instalados

pip list

Exemplo de saída:

Package    Version
---------- -------
pip        24.0
requests   2.31.0
setuptools 69.0.3

Mostrar detalhes de um pacote

pip show requests

A saída inclui versão, autor, licença, local de instalação e — o que é importante — o que ele requer e o que o requer:

Name: requests
Version: 2.31.0
Summary: Python HTTP for Humans.
Home-page: https://requests.readthedocs.io
Author: Kenneth Reitz
License: Apache 2.0
Location: /usr/lib/python3/dist-packages
Requires: certifi, charset-normalizer, idna, urllib3
Required-by:

Verificar conflitos de versão

pip check

O pip examina todos os pacotes instalados e reporta quaisquer requisitos incompatíveis. Se tudo estiver bem, o comando encerra silenciosamente.

Atualizando e removendo pacotes

Atualizar um pacote

pip install --upgrade requests

Isso instala a versão mais recente que satisfaz quaisquer restrições já presentes no seu ambiente.

Atualizar todos os pacotes (sem comando integrado)

O pip não tem um comando único para atualizar todos os pacotes instalados. Uma solução alternativa comum usando pip list e xargs:

pip list --outdated --format=freeze | cut -d = -f 1 | xargs pip install --upgrade

Use com cuidado em um ambiente de projeto — atualizações em massa podem introduzir mudanças que quebram o código. Arquivos requirements.txt com versões fixadas são uma alternativa mais segura.

Desinstalar um pacote

pip uninstall requests

O pip pede confirmação antes de remover o pacote. Passe -y para pular o prompt em scripts:

pip uninstall -y requests

Exportando dependências

Congelar o ambiente atual

pip freeze gera todos os pacotes instalados e suas versões exatas em um formato adequado para um arquivo requirements.txt:

pip freeze > requirements.txt

A saída tem este aspecto:

certifi==2024.2.2
charset-normalizer==3.3.2
idna==3.6
requests==2.31.0
urllib3==2.2.1

Compartilhe o requirements.txt com colegas de equipe ou inclua-o no seu repositório para que qualquer pessoa possa reproduzir seu ambiente com pip install -r requirements.txt.

pip e ambientes virtuais

Por padrão, o pip instala pacotes globalmente (ou por usuário com --user). Isso causa problemas quando dois projetos precisam de versões diferentes da mesma biblioteca.

A solução é um ambiente virtual: uma instalação Python isolada que tem seu próprio pip e seu próprio diretório site-packages. Quando um ambiente virtual está ativo, pip install afeta apenas esse ambiente.

# Create a virtual environment named .venv
python -m venv .venv

# Activate it (macOS / Linux)
source .venv/bin/activate

# Activate it (Windows)
.venv\Scripts\activate

# Now pip works inside the isolated environment
pip install requests

Consulte o capítulo Python Virtual Environments para o fluxo de trabalho completo.

Obtendo saída detalhada

Quando uma instalação falha, a mensagem de erro padrão pode ser enigmática. Adicione --verbose (ou -v) para ver cada etapa que o pip executa:

pip install --verbose requests

Adicione -v duas vezes (-vv) para ainda mais detalhes, incluindo as requisições HTTP que o pip faz ao PyPI.

Erros comuns e correções

Tabela de referência rápida

Capítulos relacionados

• Python Modules — entenda como o Python importa código antes de instalar pacotes de terceiros
• Python Virtual Environments — isole as dependências do projeto para que as instalações do pip nunca entrem em conflito

Prática