pip em Python: instalar pacotes, gerenciar versões e usar o PyPI

O que o pip de fato é

pip é a ferramenta que instala bibliotecas Python que você não escreveu. Quando você roda pip install requests, ele procura requests no PyPI (o Python Package Index), baixa a versão certa para sua plataforma e coloca no diretório site-packages da sua instalação Python. Depois disso, import requests funciona.

Toda instalação do Python 3 do python.org, Homebrew ou do gerenciador de pacotes do seu Linux já vem com pip. Antes de instalar qualquer coisa, confira:

python -m pip --version

Você deve ver um número de versão e um caminho para o módulo pip. Se o comando falha, a correção mais confiável é:

python -m ensurepip --upgrade

Isso puxa o pip para a sua instalação Python usando a cópia que vem com o interpretador.

python -m pip vs pip

Você vai ver as duas formas. Elas fazem quase a mesma coisa com uma diferença importante: python -m pip usa o python do seu PATH — o mesmo que seus scripts usam. pip puro usa o pip que aparecer primeiro, o que nem sempre é o mesmo.

Quando você tem mais de um Python instalado (fácil acontecer no macOS), pip puro é como você cai na situação confusa de "instalei a biblioteca mas meu código ainda diz ModuleNotFoundError".

Regra prática: use python -m pip ... quando quer certeza sobre qual interpretador recebe o pacote. pip puro está bem para trabalho rápido quando você tem certeza.

Instalando um pacote

O comando básico:

python -m pip install requests

Isso busca requests no PyPI, junto com tudo de que ele depende, e instala. Um minuto depois você pode usar:

Instalando vários pacotes de uma vez:

python -m pip install requests pandas rich

Fixando uma versão específica:

python -m pip install "django==5.0.2"
python -m pip install "requests>=2.30,<3"

As aspas importam em alguns shells — evitam que == e < sejam interpretados como operadores de shell.

Atualizando e desinstalando

python -m pip install --upgrade requests
python -m pip uninstall requests

--upgrade busca a versão mais nova que satisfaz qualquer restrição que você especifique. uninstall remove o pacote mas não suas dependências; essas ficam até você remover explicitamente.

Para manter o próprio pip atualizado:

python -m pip install --upgrade pip

Vale rodar uma vez a cada alguns meses. Versões mais novas de pip pegam mais problemas de instalação e resolvem dependências melhor.

Vendo o que está instalado

python -m pip list
python -m pip show requests

list mostra cada pacote instalado no Python atual. show requests imprime a versão, localização, dependências e licença daquele pacote específico — útil quando você está se perguntando "qual versão disso eu estou realmente usando?"

requirements.txt: anotando suas dependências

Quando um projeto tem mais do que algumas bibliotecas, anote a lista. pip freeze faz isso para você:

python -m pip freeze > requirements.txt

Isso produz um arquivo com uma dependência fixada por linha:

django==5.0.2
requests==2.31.0
rich==13.7.1

Quem clona seu repo pode reproduzir a instalação com:

python -m pip install -r requirements.txt

pip freeze captura tudo instalado, incluindo dependências transitivas. Bom para reprodutibilidade exata, mas barulhento quando você só quer as bibliotecas de topo que seu código de fato importa. Muitos projetos mantêm um requirements.txt feito à mão com dependências diretas, e deixam o pip resolver as transitivas.

Para projetos modernos, pyproject.toml (emparelhado com ferramentas como pip-tools, uv, poetry ou hatch) está substituindo o requirements.txt. O conceito é o mesmo — "anote as dependências, rode um comando para instalar" — mas o formato do arquivo é mais estruturado.

Sempre instale num ambiente virtual

Todo projeto Python real deve ter um ambiente virtual. É uma pasta local do projeto com seu próprio python e seus próprios pacotes instalados — então pip install num projeto não afeta outro.

O setup de duas linhas:

python -m venv .venv
source .venv/bin/activate    # macOS / Linux
# or .venv\Scripts\activate on Windows

Uma vez ativado, python -m pip install requests instala no venv. Seu Python de sistema fica limpo. Cobrimos com mais profundidade na página de Ambientes Virtuais.

Se algum dia você roda pip install e vê um aviso sobre instalar no Python de sistema (ou uma mensagem te mandando passar --break-system-packages), pare. Essa é sua pista para criar um venv.

Quando o pip não consegue instalar um pacote

Alguns modos de falha comuns e o que significam:

• Could not find a version that satisfies the requirement … — geralmente typo no nome do pacote, ou o pacote exige um Python mais novo do que você tem.
• error: Microsoft Visual C++ 14.0 or greater is required (Windows) — o pacote tem extensão nativa e precisa de toolchain C++. Ou instale as Build Tools da Microsoft ou procure uma wheel pré-construída (a maioria dos pacotes populares inclui).
• Permission denied — você está tentando instalar no Python de sistema sem root. A correção certa não é sudo pip install — é um ambiente virtual.
• ModuleNotFoundError depois de instalar — quase sempre caso em que o pip install colocou o pacote num Python diferente do que está rodando seu script. Confira which python e which pip (macOS/Linux) ou where python / where pip (Windows). Ou, mais confiável, use python -m pip install ....

Alternativas modernas ao pip

Algumas ferramentas que você vai ver mencionadas — todas compatíveis com pip e resolvem dores específicas:

• uv — um instalador e resolvedor muito mais rápido. Substituto drop-in para a maioria dos comandos pip.
• pipx — instala ferramentas de linha de comando (como black, ruff, httpie) em venvs isolados para ficarem disponíveis globalmente sem conflitar com dependências de projeto.
• poetry e hatch — gerenciadores de projeto que combinam manipulação de ambiente virtual, resolução de dependências e build numa ferramenta só.

Você não precisa de nenhum deles no primeiro dia. Aprenda pip primeiro; recorra aos outros quando a dor que eles resolvem se tornar sua.

Próxima: ambientes virtuais

Pacotes e ambientes virtuais andam juntos. Você viu por quê; a próxima página caminha por venv em detalhe — criando, ativando, desativando e as pequenas convenções que mantêm projetos Python organizados.