Guia completo sobre pip: instalar pacotes, gerenciar dependências, pip vs pip3, pip-tools, segurança e alternativas como poetry e uv.

pip: O que É e Como Funciona | Python Brasil | Python Brasil

O que é pip?

O pip (acrônimo recursivo de “pip installs packages”) é o gerenciador de pacotes oficial do Python. Ele permite instalar, atualizar e remover bibliotecas disponíveis no PyPI (Python Package Index), o repositório público em pypi.org com mais de 500.000 pacotes.

O pip foi criado por Ian Bicking em 2008 como substituto ao easy_install, tornando-se a ferramenta padrão da comunidade. A partir do Python 3.4, o pip é incluído automaticamente na instalação padrão da linguagem. Não é necessário instalar separadamente.

pip vs pip3: qual usar?

Em sistemas onde Python 2 e Python 3 coexistem, pode haver dois executáveis: pip e pip3. A diferença é simples:

pip pode apontar para Python 2 ou Python 3, dependendo da configuração do sistema
pip3 aponta especificamente para Python 3

Para evitar ambiguidade, a forma mais segura é sempre invocar o pip como módulo da versão específica do Python:

# Forma segura e explícita — usa exatamente o pip do python3
python3 -m pip install requests

# Verificar qual Python o pip está usando
pip --version
# pip 24.0 from /usr/local/lib/python3.12/... (python 3.12)

pip3 --version
# mesmo resultado se python3 for a versão padrão

Dentro de um ambiente virtual ativado, tanto pip quanto pip3 sempre apontam para o ambiente correto. Fora de ambientes virtuais, prefira python3 -m pip.

Comandos essenciais do pip

# Instalar um pacote
pip install requests

# Instalar versão específica
pip install django==4.2.7

# Instalar com restrição de versão mínima
pip install "fastapi>=0.100.0"

# Instalar intervalo de versões
pip install "numpy>=1.24,<2.0"

# Atualizar um pacote
pip install --upgrade requests

# Atualizar o próprio pip
pip install --upgrade pip

# Desinstalar
pip uninstall requests

# Listar pacotes instalados
pip list

# Listar pacotes desatualizados
pip list --outdated

# Informações detalhadas sobre um pacote
pip show django

# Verificar dependências quebradas
pip check

Opções avançadas de instalação

# Instalar no diretório do usuário (sem permissão de admin)
pip install --user requests

# Instalar em modo editável (desenvolvimento local)
# Mudanças no código refletem imediatamente sem reinstalar
pip install -e .
pip install -e /caminho/para/meu-pacote

# Instalar sem usar o cache local
pip install --no-cache-dir tensorflow

# Instalar a partir de um repositório Git
pip install git+https://github.com/usuario/repo.git
pip install git+https://github.com/usuario/repo.git@v1.2.3

# Instalar a partir de um arquivo local
pip install ./dist/meu_pacote-1.0.0-py3-none-any.whl

# Instalar sem dependências
pip install --no-deps meu-pacote

Gerenciando dependências com requirements.txt

O arquivo requirements.txt é a forma tradicional de declarar dependências de um projeto Python:

# Gerar requirements a partir do ambiente atual
pip freeze > requirements.txt

# Instalar todas as dependências do arquivo
pip install -r requirements.txt

# Instalar dependências de desenvolvimento separadamente
pip install -r requirements-dev.txt

Exemplo de requirements.txt bem estruturado:

# Dependências de produção
django==4.2.7
djangorestframework==3.14.0
psycopg2-binary==2.9.9
gunicorn==21.2.0

# requirements-dev.txt
-r requirements.txt
pytest==7.4.3
black==23.11.0
mypy==1.7.1

pip-tools: dependências determinísticas

O pip-tools é um conjunto de utilitários para gerenciar dependências de forma mais robusta. Ele separa as dependências diretas das dependências transitivas (dependências das dependências):

pip install pip-tools

# requirements.in — apenas suas dependências diretas
# django>=4.2
# requests
# celery

# Compilar: resolve e fixa TODAS as versões (diretas + transitivas)
pip-compile requirements.in
# gera requirements.txt com versões fixas e hashes

# Sincronizar o ambiente com o arquivo compilado
pip-sync requirements.txt

O pip-compile gera um requirements.txt que inclui comentários indicando por que cada pacote está presente, tornando as dependências completamente auditáveis.

Configuração com pip.conf

O pip pode ser configurado globalmente ou por projeto por meio de arquivos de configuração:

# ~/.config/pip/pip.conf (Linux/macOS)
# %APPDATA%\pip\pip.ini (Windows)

[global]
# Usar um mirror nacional (mais rápido no Brasil)
index-url = https://pypi.org/simple/

# Timeout em segundos
timeout = 60

# Não confirmar desinstalação
yes = true

[install]
# Sempre instalar no usuário por padrão
user = true

Para projetos com registro privado (Artifactory, Nexus, AWS CodeArtifact):

[global]
extra-index-url = https://usuario:senha@meu-registry.empresa.com/simple/

Segurança: verificação de hashes

Para garantir que os pacotes instalados são exatamente os esperados (proteção contra ataques de supply chain), use verificação de hash:

# Instalar com verificação de hash
pip install --require-hashes -r requirements.txt

O requirements.txt com hashes fica assim (gerado automaticamente pelo pip-tools):

requests==2.31.0 \
    --hash=sha256:58cd2187423839... \
    --hash=sha256:942c5a758f98d...

Outra boa prática de segurança é auditar pacotes instalados em busca de vulnerabilidades conhecidas:

pip install pip-audit
pip-audit

Erros comuns e suas soluções

# Erro: externally-managed-environment (Python 3.11+)
# Solução: use um ambiente virtual ou --break-system-packages (não recomendado)
python3 -m venv .venv && source .venv/bin/activate

# Erro: pip: command not found
python3 -m ensurepip --upgrade

# Erro: SSL certificate verify failed
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org requests

# Erro: versão incompatível de dependência
pip install "pacote-a==1.0" "pacote-b==2.0"
# se conflito, use um resolver como poetry ou uv

# Erro: permissão negada
pip install --user requests  # instala no diretório do usuário

Alternativas modernas ao pip

O ecossistema Python evoluiu e existem ferramentas que vão além do pip:

Poetry: gerencia dependências, ambientes virtuais e publicação em um único fluxo. Usa pyproject.toml como único arquivo de configuração. Resolve conflitos de dependência de forma mais sofisticada.

pipx: instala ferramentas CLI Python em ambientes isolados automaticamente. Ideal para instalar Black, pytest, mypy e outras ferramentas de linha de comando sem poluir o ambiente global.

uv: gerenciador de pacotes escrito em Rust, lançado pela Astral em 2024. É de 10 a 100 vezes mais rápido que o pip e está se tornando o padrão da indústria rapidamente.

# pipx — ferramentas CLI isoladas
pipx install black
pipx install httpie
black --version  # disponível globalmente

# uv — substituto ultrarrápido do pip
pip install uv
uv pip install django           # sintaxe compatível com pip
uv pip sync requirements.txt    # sincronização de ambiente
uv venv                         # criar ambiente virtual

Boas práticas com pip

Sempre use pip dentro de um ambiente virtual para evitar conflitos entre projetos e não poluir o Python do sistema. Fixe versões das dependências para garantir reprodutibilidade. Use pip check periodicamente para identificar incompatibilidades. Mantenha o pip atualizado com pip install --upgrade pip. Para projetos novos, considere usar uv ou Poetry como alternativas mais modernas e robustas.

Termos Relacionados

Python - A linguagem de programação
Virtualenv - Ambientes virtuais Python
Pacote - Estrutura e distribuição de código