Python pip

O Python já vem com muita coisa pronta: math, random, datetime, json… É a biblioteca padrão, que você conheceu na aula Módulos e import. Mas o mundo do Python é muito maior do que isso: milhares de pessoas escrevem módulos e os deixam disponíveis de graça, para qualquer um usar. Para trazer esses módulos para o seu computador existe o pip, o instalador de pacotes do Python. Nesta aula você vai usá-lo de verdade, no terminal da Ana, e vai entender por que a primeira tentativa, no Ubuntu, sempre dá erro.

Você vai aprender

O que é um pacote e o que é o PyPI, a "loja" de onde o pip baixa.
Por que o pip install do Ubuntu responde externally-managed-environment, e o que é a PEP 668.
As três saídas: o pacote do apt, o ambiente virtual e (para programas) o pipx.
A instalar, listar, ver detalhes, atualizar e remover pacotes: pip install, list, show, uninstall.
A anotar os pacotes do projeto num requirements.txt com pip freeze, e a reinstalar tudo com pip install -r.
Os erros reais: nome digitado errado, sem internet, esqueceu de ativar o ambiente.

Esta é uma aula de terminal

O pip é um programa que roda no terminal do seu computador, não dentro de um programa Python. Por isso, quase tudo aqui é mostrado em janelas de terminal, com o que o Ubuntu da Ana respondeu de verdade. O editor do guia (o "Experimente") não instala pacotes; as caixas desta aula treinam o que dá para treinar nele: ler um requirements.txt e reconhecer o erro de pacote que falta.

A ideia: a loja de aplicativos do Python

Pense no celular da Ana. Ele já vem com alguns aplicativos de fábrica: a câmera, o relógio, a calculadora. Quando ela quer outro (um app de receitas, um jogo), abre a loja de aplicativos, procura pelo nome e toca em "instalar". Ninguém precisa escrever o app; alguém já escreveu e deixou na loja.

No Python é igual:

No celular	No Python
Os apps de fábrica	A biblioteca padrão: `math`, `random`, `json`… (já vem com o Python)
Um app da loja	Um pacote (em inglês, package): um ou mais módulos que outra pessoa escreveu
A loja de aplicativos	O PyPI (Python Package Index, "índice de pacotes do Python"), no site `pypi.org`, com centenas de milhares de pacotes
O botão "instalar"	O comando `pip install nome-do-pacote`

O nome pip é uma brincadeira recursiva em inglês: "pip installs packages", "o pip instala pacotes". Nesta aula, o pacote de exemplo é o requests ("pedidos"), um dos mais usados do mundo: ele deixa um programa Python conversar com sites da internet com uma linha só.

1. O `pip` já está aí?

No Ubuntu 26.04 da Ana, o pip veio instalado junto com o Python (é o pacote python3-pip do Ubuntu). Para conferir, peça a versão:

$ python3 --version
Python 3.14.4
$ pip --version
pip 25.1.1 from /usr/lib/python3/dist-packages/pip (python 3.14)
$ pip3 --version
pip 25.1.1 from /usr/lib/python3/dist-packages/pip (python 3.14)

pip 25.1.1: A versão do pip. Ele tem as versões dele, separadas das do Python.
from /usr/lib/python3/dist-packages/pip: "De onde" ele veio: a pasta do sistema onde o Ubuntu guarda os módulos Python que ele instalou.
(python 3.14): Para qual Python esse pip instala. Isso importa: cada Python tem o seu pip.

pip e pip3 são o mesmo programa (o "3" é de Python 3). Existe ainda uma terceira forma, que você vai ver muito em tutoriais: python3 -m pip. O -m quer dizer "rode o módulo": você pede ao próprio python3 que rode o pip dele. A vantagem é não ter dúvida de qual Python vai receber o pacote. Para ver o que já está instalado, use list ("listar"):

$ python3 -m pip list
Package           Version
----------------- ---------------
command-not-found 0.3
packaging         26.0
pip               25.1.1
python-apt        3.1.0+ubuntu1.1
wheel             0.46.3

Poucos pacotes, e todos foram instalados pelo Ubuntu, não pela Ana. O command-not-found, por exemplo, é o programa que sugere "você quis dizer python3?" quando alguém digita python. Guarde essa informação: o próprio Ubuntu usa o Python para fazer o trabalho dele.

Não tem o pip?

Se o seu terminal responder Comando 'pip' não encontrado, o pacote do Ubuntu não está instalado. Instale com sudo apt install python3-pip python3-venv (o sudo pede a sua senha; detalhes na aula Instalar o Python).

2. A primeira tentativa: `externally-managed-environment`

A Ana quer usar o requests. Ela confere que ele não existe ainda (o Python responde com um ModuleNotFoundError, "módulo não encontrado") e manda instalar:

$ python3 -c "import requests"
Traceback (most recent call last):
  File "<string>", line 1, in <module>
    import requests
ModuleNotFoundError: No module named 'requests'
$ pip install requests
error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.

    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.

    See /usr/share/doc/python3.14/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

(O python3 -c "…" roda um pedacinho de código direto do terminal, sem criar arquivo: o -c é de "comando".) O pip se recusou a instalar. Não é defeito: é de propósito. A mensagem está em inglês; leia com calma, parte por parte:

error: externally-managed-environment: "Erro: ambiente gerenciado por fora." Este Python pertence ao sistema, e quem cuida dos pacotes dele é outro programa (o apt do Ubuntu), não o pip.
try apt install python3-xyz: Primeira saída: "tente o apt install python3-xyz, onde xyz é o pacote que você quer". Ou seja, peça o pacote ao Ubuntu.
create a virtual environment using python3 -m venv: Segunda saída: "crie um ambiente virtual" e instale lá dentro, à vontade.
pipx install xyz: Terceira saída, para quando o pacote é um programa que você quer usar no terminal (e não um módulo para importar).
--break-system-packages: "Quebrar os pacotes do sistema": uma opção que força a instalação. O nome já avisa o risco.
hint: See PEP 668: "Dica: veja a PEP 668", o documento que criou essa regra.

Mesmo com pip3, com python3 -m pip ou com pip install --user requests (que instalaria só para a Ana), a resposta é a mesma, letra por letra.

Por que o Ubuntu bloqueia: a PEP 668

Uma PEP (Python Enhancement Proposal, "proposta de melhoria do Python") é um documento público em que a comunidade decide uma regra do Python. A PEP 668 resolveu um problema antigo: o mesmo Python servia ao mesmo tempo para os programas da pessoa e para os programas do sistema. Lembra do command-not-found e do python-apt na lista lá de cima? São ferramentas do Ubuntu escritas em Python. Se a Ana instalasse com o pip uma versão diferente de um módulo que elas usam, uma atualização do sistema poderia parar de funcionar, e ninguém saberia por quê.

A solução: o sistema coloca um arquivo chamado EXTERNALLY-MANAGED na pasta do Python, e o pip, ao encontrá-lo, se recusa a mexer ali. A mensagem que você leu vem desse arquivo:

$ cat /usr/lib/python3.14/EXTERNALLY-MANAGED
[externally-managed]
Error=To install Python packages system-wide, try apt install
 python3-xyz, where xyz is the package you are trying to
 install.

 If you wish to install a non-Debian-packaged Python package,
 create a virtual environment using python3 -m venv path/to/venv.
 Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
 sure you have python3-full installed.

 If you wish to install a non-Debian packaged Python application,
 it may be easiest to use pipx install xyz, which will manage a
 virtual environment for you. Make sure you have pipx installed.

 See /usr/share/doc/python3.14/README.venv for more information.

Em outros sistemas

O Debian (desde a versão 12) e outras distribuições fazem o mesmo; o Ubuntu, desde a 23.04. Por isso tantos tutoriais antigos mandam rodar só pip install e, no seu computador, dá esse erro. No Windows e no macOS com o Python baixado do python.org, não há esse arquivo e o pip install funciona direto; mesmo assim, a boa prática é a mesma de todo lugar: um ambiente virtual por projeto.

3. Saída 1: o pacote do Ubuntu (`apt`)

Os pacotes Python mais famosos também existem como pacotes do Ubuntu, com o nome python3- na frente. O apt-cache policy mostra se existe e qual versão o Ubuntu oferece:

$ apt-cache policy python3-requests
python3-requests:
  Instalado: (nenhum)
  Candidato: 2.32.5+dfsg-1ubuntu1.1
  Tabela de versão:
     2.32.5+dfsg-1ubuntu1.1 500
        500 http://archive.ubuntu.com/ubuntu resolute-updates/main amd64 Packages
        500 http://security.ubuntu.com/ubuntu resolute-security/main amd64 Packages
     2.32.5+dfsg-1ubuntu1 500
        500 http://archive.ubuntu.com/ubuntu resolute/main amd64 Packages

"Instalado: (nenhum)", "Candidato: 2.32.5": existe, ainda não está instalado, e a versão é a 2.32.5. Instalar pacotes do sistema exige ser administrador, então o comando leva sudo na frente. Sem ele, o apt reclama:

$ apt install python3-requests

WARNING: apt does not have a stable CLI interface. Use with caution in scripts.

Erro: Não foi possível abrir arquivo de trava /var/lib/dpkg/lock-frontend - open (13: Permissão negada)
Erro: Não é possível adquirir a trava da interface do dpkg (/var/lib/dpkg/lock-frontend), você é root?

"Você é root?" (o administrador). O certo é sudo apt install python3-requests, que pede a senha da Ana e instala. (É o mesmo jeito de instalar qualquer programa do Ubuntu, como na aula Instalar o Python; a saída dele aqui foi omitida.)

O `apt` é bom quando…	…mas tem limites
O pacote é famoso e você quer o mesmo em todos os seus programas	Nem todo pacote do PyPI existe no Ubuntu
Você quer que as atualizações do sistema cuidem dele	A versão é a que o Ubuntu escolheu (a 2.32.5, aqui), e não a mais nova do PyPI
—	Precisa de `sudo`, e vale para o computador inteiro

4. Saída 2: o ambiente virtual (o jeito de todo dia)

Um ambiente virtual é uma pasta com uma "cópia" particular do Python, só para um projeto. Lá dentro, o pip é seu: instala o que quiser, na versão que quiser, sem sudo e sem encostar no Python do sistema. Ele tem uma aula só para ele, Ambientes Virtuais (venv); aqui você só precisa de três comandos para começar. A Ana cria a pasta do projeto da lojinha, cria o ambiente e o ativa:

$ mkdir loja
$ cd loja
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) ana@notebook:~/loja$ which pip
/home/ana/loja/.venv/bin/pip
(.venv) ana@notebook:~/loja$ pip list
Package Version
------- -------
pip     25.1.1

python3 -m venv .venv: Cria o ambiente virtual numa pasta chamada .venv, dentro do projeto.
source .venv/bin/activate: Ativa o ambiente: a partir daqui, python e pip são os de dentro da .venv.
(.venv): O começo do prompt mudou: é o terminal avisando que o ambiente está ativo.
which pip: "Qual pip?": agora é o que está em /home/ana/loja/.venv/bin/.
pip list: Um ambiente novo vem vazio: só o próprio pip.

5. `pip install`: instalando de verdade

Com o ambiente ativo, o mesmo comando que deu erro agora funciona:

(.venv) ana@notebook:~/loja$ pip install requests
Collecting requests
  Downloading requests-2.34.2-py3-none-any.whl.metadata (4.8 kB)
Collecting charset_normalizer<4,>=2 (from requests)
  Downloading charset_normalizer-3.5.2-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.metadata (46 kB)
Collecting idna<4,>=2.5 (from requests)
  Downloading idna-3.20-py3-none-any.whl.metadata (7.2 kB)
Collecting urllib3<3,>=1.26 (from requests)
  Downloading urllib3-2.8.0-py3-none-any.whl.metadata (7.4 kB)
Collecting certifi>=2023.5.7 (from requests)
  Downloading certifi-2026.7.22-py3-none-any.whl.metadata (2.5 kB)
Downloading requests-2.34.2-py3-none-any.whl (73 kB)
Downloading charset_normalizer-3.5.2-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (255 kB)
Downloading idna-3.20-py3-none-any.whl (69 kB)
Downloading urllib3-2.8.0-py3-none-any.whl (135 kB)
Downloading certifi-2026.7.22-py3-none-any.whl (136 kB)
Installing collected packages: urllib3, idna, charset_normalizer, certifi, requests

Successfully installed certifi-2026.7.22 charset_normalizer-3.5.2 idna-3.20 requests-2.34.2 urllib3-2.8.0

Muita coisa para um comando só. Vá por partes:

Collecting requests: "Juntando o requests": o pip foi ao PyPI e achou a versão mais nova, a 2.34.2.
Collecting charset_normalizer<4,>=2 (from requests): O requests precisa de outros pacotes para funcionar: as dependências. Esta linha diz "o requests pediu um charset_normalizer com versão menor que 4 e maior ou igual a 2". O pip resolve isso sozinho.
Downloading … .whl (73 kB): Baixando o arquivo do pacote. .whl (de wheel, "roda") é o formato de pacote pronto para instalar.
Installing collected packages: …: Instalando os cinco: o requests e as quatro dependências.
Successfully installed …: "Instalado com sucesso", com a versão de cada um.

Pediu um, vieram cinco. É normal: pacotes são feitos de outros pacotes, como um bolo é feito de farinha, ovos e açúcar. (No seu computador, os números das versões e os tamanhos provavelmente vão ser outros: os pacotes são atualizados o tempo todo, e estes são os do dia em que a aula foi escrita, outubro de 2026.) Agora a lista do ambiente mostra todos:

(.venv) ana@notebook:~/loja$ pip list
Package            Version
------------------ ---------
certifi            2026.7.22
charset-normalizer 3.5.2
idna               3.20
pip                25.1.1
requests           2.34.2
urllib3            2.8.0

Usando o pacote

Instalado, o pacote se importa igual a um módulo da biblioteca padrão, com import. A Ana escreve um programinha que visita um site de exemplo:

import requests

resposta = requests.get("https://example.com")
print("Código:", resposta.status_code)
print("Tipo:", resposta.headers["Content-Type"])
print("Tamanho:", len(resposta.text), "caracteres")

import requests: Importa o pacote que acabou de ser instalado.
requests.get("https://example.com"): "Pegue" a página desse endereço, como o navegador faz. A resposta do site fica na variável resposta.
resposta.status_code: O código da resposta: 200 quer dizer "deu certo" (o famoso 404 é "página não encontrada").
resposta.headers["Content-Type"]: O tipo do conteúdo que o site mandou.
resposta.text: O conteúdo da página, como texto.

(.venv) ana@notebook:~/loja$ python baixar.py
Código: 200
Tipo: text/html; charset=utf-8
Tamanho: 577 caracteres

Repare que, com o ambiente ativo, o comando python (sem o 3) existe: é o Python da .venv. Fora do ambiente, no Ubuntu, só existe python3.

6. `pip show`: os detalhes de um pacote

Para saber mais de um pacote instalado (versão, de quem ele depende, onde ficou), use show ("mostrar"):

(.venv) ana@notebook:~/loja$ pip show requests
Name: requests
Version: 2.34.2
Summary: Python HTTP for Humans.
Home-page:
Author:
Author-email: Kenneth Reitz <me@kennethreitz.org>
License: Apache-2.0
Location: /home/ana/loja/.venv/lib/python3.14/site-packages
Requires: certifi, charset_normalizer, idna, urllib3
Required-by:

Name / Version: Nome e versão instalada.
Summary: Um resumo de uma linha: "HTTP em Python para humanos".
Location: A pasta onde ele foi parar: site-packages, dentro da .venv da lojinha. O sistema ficou intocado.
Requires: "Precisa de": as dependências.
Required-by: "É exigido por": quais outros pacotes instalados dependem dele (nenhum, aqui).

7. `pip freeze` e o `requirements.txt`

Daqui a um mês, a Ana vai querer rodar a lojinha no computador da Bia. Como a Bia vai saber quais pacotes instalar, e em quais versões? O pip freeze ("congelar") imprime a lista exata, num formato que o próprio pip entende:

(.venv) ana@notebook:~/loja$ pip freeze
certifi==2026.7.22
charset-normalizer==3.5.2
idna==3.20
requests==2.34.2
urllib3==2.8.0
(.venv) ana@notebook:~/loja$ pip freeze > requirements.txt
(.venv) ana@notebook:~/loja$ cat requirements.txt
certifi==2026.7.22
charset-normalizer==3.5.2
idna==3.20
requests==2.34.2
urllib3==2.8.0

requests==2.34.2: Uma linha por pacote: o nome, dois sinais de igual e a versão exata. É uma "foto" do ambiente.
> requirements.txt: O > do terminal manda a saída para um arquivo em vez da tela. requirements.txt ("requisitos") é o nome que todo projeto Python usa para essa lista.

Do outro lado, a Bia cria o ambiente dela e instala tudo de uma vez com -r (de requirement, "leia a lista deste arquivo"). Para mostrar, a Ana tira o requests do ambiente e pede a lista de volta:

(.venv) ana@notebook:~/loja$ pip uninstall -y requests
Found existing installation: requests 2.34.2
Uninstalling requests-2.34.2:
  Successfully uninstalled requests-2.34.2
(.venv) ana@notebook:~/loja$ pip install -r requirements.txt
Requirement already satisfied: certifi==2026.7.22 in ./.venv/lib/python3.14/site-packages (from -r requirements.txt (line 1)) (2026.7.22)
Requirement already satisfied: charset-normalizer==3.5.2 in ./.venv/lib/python3.14/site-packages (from -r requirements.txt (line 2)) (3.5.2)
Requirement already satisfied: idna==3.20 in ./.venv/lib/python3.14/site-packages (from -r requirements.txt (line 3)) (3.20)
Collecting requests==2.34.2 (from -r requirements.txt (line 4))
  Using cached requests-2.34.2-py3-none-any.whl.metadata (4.8 kB)
Requirement already satisfied: urllib3==2.8.0 in ./.venv/lib/python3.14/site-packages (from -r requirements.txt (line 5)) (2.8.0)
Using cached requests-2.34.2-py3-none-any.whl (73 kB)
Installing collected packages: requests
Successfully installed requests-2.34.2

"Requirement already satisfied" quer dizer "requisito já atendido": o que já estava lá, o pip pulou. Só o requests, que faltava, foi instalado, e da versão anotada (2.34.2). "Using cached" ("usando o guardado"): o pip guarda uma cópia do que já baixou e não baixa de novo.

O que vai para o git, o que não vai

O requirements.txt é pequeno e é a "receita" do projeto: guarde-o junto com o código. A pasta .venv é grande e pode ser recriada a qualquer momento a partir da receita: não a copie para outro computador nem a coloque no git.

Um requirements.txt é só um arquivo de texto, então um programa Python consegue lê-lo como qualquer outro (a aula Lendo Arquivos mostra como). Experimente:

Missão: o programa mostra as linhas do requirements.txt do jeito que estão. Troque o print para mostrar cada pacote no formato requests na versão 2.34.2. Dica: linha.split("==") separa o nome da versão (aula Métodos de Texto).

with open("requirements.txt", encoding="utf-8") as arquivo:
    for linha in arquivo:
        linha = linha.strip()
        print(linha)

certifi==2026.7.22
charset-normalizer==3.5.2
idna==3.20
requests==2.34.2
urllib3==2.8.0

with open("requirements.txt", encoding="utf-8") as arquivo:
    for linha in arquivo:
        linha = linha.strip()
        nome, versao = linha.split("==")
        print(f"{nome} na versão {versao}")

8. Escolher a versão, atualizar e remover

Uma versão exata: `==`

Às vezes um projeto precisa de uma versão mais antiga. Escreva o nome, == e a versão. As aspas evitam que o terminal estranhe algum símbolo:

(.venv) ana@notebook:~/loja$ pip install "requests==2.32.3"
Collecting requests==2.32.3
  Downloading requests-2.32.3-py3-none-any.whl.metadata (4.6 kB)
Requirement already satisfied: charset-normalizer<4,>=2 in ./.venv/lib/python3.14/site-packages (from requests==2.32.3) (3.5.2)
Requirement already satisfied: idna<4,>=2.5 in ./.venv/lib/python3.14/site-packages (from requests==2.32.3) (3.20)
Requirement already satisfied: urllib3<3,>=1.21.1 in ./.venv/lib/python3.14/site-packages (from requests==2.32.3) (2.8.0)
Requirement already satisfied: certifi>=2017.4.17 in ./.venv/lib/python3.14/site-packages (from requests==2.32.3) (2026.7.22)
Downloading requests-2.32.3-py3-none-any.whl (64 kB)
Installing collected packages: requests
  Attempting uninstall: requests
    Found existing installation: requests 2.34.2
    Uninstalling requests-2.34.2:
      Successfully uninstalled requests-2.34.2
Successfully installed requests-2.32.3

O pip tirou a 2.34.2 ("Attempting uninstall", "tentando desinstalar") e pôs a 2.32.3 no lugar. Num ambiente cabe uma versão de cada pacote por vez.

A mais nova: `--upgrade`

Pedir de novo um pacote que já está instalado não faz nada (o pip responde "Requirement already satisfied"). Para trocar pela versão mais nova, use --upgrade ("atualizar") ou a forma curta -U:

(.venv) ana@notebook:~/loja$ pip install --upgrade requests
Requirement already satisfied: requests in ./.venv/lib/python3.14/site-packages (2.32.3)
Collecting requests
  Using cached requests-2.34.2-py3-none-any.whl.metadata (4.8 kB)
Requirement already satisfied: charset_normalizer<4,>=2 in ./.venv/lib/python3.14/site-packages (from requests) (3.5.2)
Requirement already satisfied: idna<4,>=2.5 in ./.venv/lib/python3.14/site-packages (from requests) (3.20)
Requirement already satisfied: urllib3<3,>=1.26 in ./.venv/lib/python3.14/site-packages (from requests) (2.8.0)
Requirement already satisfied: certifi>=2023.5.7 in ./.venv/lib/python3.14/site-packages (from requests) (2026.7.22)
Using cached requests-2.34.2-py3-none-any.whl (73 kB)
Installing collected packages: requests
  Attempting uninstall: requests
    Found existing installation: requests 2.32.3
    Uninstalling requests-2.32.3:
      Successfully uninstalled requests-2.32.3
Successfully installed requests-2.34.2
(.venv) ana@notebook:~/loja$ python -c "import requests; print(requests.__version__)"
2.34.2

Remover: `pip uninstall`

uninstall ("desinstalar") mostra o que vai apagar e pergunta antes. Responda y (de yes, "sim"):

(.venv) ana@notebook:~/loja$ pip uninstall requests
Found existing installation: requests 2.34.2
Uninstalling requests-2.34.2:
  Would remove:
    /home/ana/loja/.venv/lib/python3.14/site-packages/requests-2.34.2.dist-info/*
    /home/ana/loja/.venv/lib/python3.14/site-packages/requests/*
Proceed (Y/n)? y
  Successfully uninstalled requests-2.34.2

"Would remove" é "removeria"; "Proceed (Y/n)?", "continuar?". O Y maiúsculo indica a resposta padrão: só apertar Enter também vale como sim. Com -y (como na seção anterior), o pip não pergunta. Repare que só o requests saiu: as dependências que vieram com ele continuam lá.

Formas diferentes de instalar um pacote

Jeito	Exemplo	Quando usar
`pip install` num ambiente virtual ativo	`pip install requests`	Quase sempre. Cada projeto com os seus pacotes, nas versões que ele precisa, sem `sudo`
`python -m pip` no ambiente	`python -m pip install requests`	O mesmo, sem dúvida de qual Python recebe o pacote. É a forma que a documentação oficial prefere
Pacote do sistema	`sudo apt install python3-requests`	Um pacote famoso que você quer em todos os scripts soltos do computador, na versão do Ubuntu
`pipx`	`pipx install nome`	O pacote é um programa de terminal (não um módulo para importar). O `pipx` (instale com `sudo apt install pipx`) cria um ambiente só para ele, sozinho
`--break-system-packages`	`pip install --break-system-packages requests`	Evite. Força o `pip` a mexer no Python do sistema; pode quebrar ferramentas do Ubuntu numa atualização futura

Quando dá errado

error: externally-managed-environment

Você já viu na seção 2: é o pip install fora de um ambiente virtual, no Python do sistema. Como consertar: crie e ative um ambiente (python3 -m venv .venv e source .venv/bin/activate) e repita o comando; ou use sudo apt install python3-nome.

O nome do pacote digitado errado

(.venv) ana@notebook:~/loja$ pip install requets
ERROR: Could not find a version that satisfies the requirement requets (from versions: none)
ERROR: No matching distribution found for requets

"Não achei uma versão que atenda ao requisito requets (versões: nenhuma)." O pip não sugere o nome certo: ele só sabe que não existe nenhum pacote com esse nome no PyPI. Como consertar: confira a grafia (era requests, com s antes do t). Na dúvida, procure o nome exato em pypi.org.

Cuidado com nomes parecidos

Qualquer pessoa pode publicar no PyPI, e já houve casos de pacotes maliciosos com nomes quase iguais aos famosos, esperando um erro de digitação. Copie o nome da página oficial do pacote e desconfie de nomes com uma letra trocada.

Sem internet

O pip baixa do PyPI, então precisa de internet. Sem ela, ele tenta de novo cinco vezes e desiste:

(.venv) ana@notebook:~/loja$ pip install rich
WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None)) after connection broken by 'NewConnectionError('<pip._vendor.urllib3.connection.HTTPSConnection object at 0x7f00f73296a0>: Failed to establish a new connection: [Errno -3] Falha temporário na resolução de nome')': /simple/rich/
WARNING: Retrying (Retry(total=3, connect=None, read=None, redirect=None, status=None)) after connection broken by 'NewConnectionError('<pip._vendor.urllib3.connection.HTTPSConnection object at 0x7f00f732c7d0>: Failed to establish a new connection: [Errno -3] Falha temporário na resolução de nome')': /simple/rich/
WARNING: Retrying (Retry(total=2, connect=None, read=None, redirect=None, status=None)) after connection broken by 'NewConnectionError('<pip._vendor.urllib3.connection.HTTPSConnection object at 0x7f00f732c910>: Failed to establish a new connection: [Errno -3] Falha temporário na resolução de nome')': /simple/rich/
WARNING: Retrying (Retry(total=1, connect=None, read=None, redirect=None, status=None)) after connection broken by 'NewConnectionError('<pip._vendor.urllib3.connection.HTTPSConnection object at 0x7f00f732ca50>: Failed to establish a new connection: [Errno -3] Falha temporário na resolução de nome')': /simple/rich/
WARNING: Retrying (Retry(total=0, connect=None, read=None, redirect=None, status=None)) after connection broken by 'NewConnectionError('<pip._vendor.urllib3.connection.HTTPSConnection object at 0x7f00f732cb90>: Failed to establish a new connection: [Errno -3] Falha temporário na resolução de nome')': /simple/rich/
ERROR: Could not find a version that satisfies the requirement rich (from versions: none)
ERROR: No matching distribution found for rich

Cada WARNING: Retrying é uma nova tentativa ("total=4", "total=3"… são as que ainda restam). O pedaço que explica tudo é Failed to establish a new connection ("não consegui me conectar") e Falha temporário na resolução de nome ("falha temporária ao resolver o nome"): o computador não conseguiu achar o endereço do PyPI. (O "temporário" com erro de concordância está assim mesmo na tradução do sistema.) O final é igual ao do nome errado, o que confunde: leia as linhas de cima antes de concluir que o pacote não existe. Como consertar: confira a internet e tente de novo.

Instalou, mas o Python diz que não existe

A Ana abriu um terminal novo no dia seguinte e rodou o programa:

$ cd loja
$ python3 baixar.py
Traceback (most recent call last):
  File "/home/ana/loja/baixar.py", line 1, in <module>
    import requests
ModuleNotFoundError: No module named 'requests'

Traceback (most recent call last):: "Rastro (a chamada mais recente por último)": o começo de toda mensagem de erro do Python.
File "/home/ana/loja/baixar.py", line 1: O erro foi na linha 1 do baixar.py.
import requests: A linha culpada.
ModuleNotFoundError: No module named 'requests': "Não existe módulo chamado requests".

Mas ela instalou ontem! Instalou, sim: dentro da .venv. Repare no prompt: não começa com (.venv). Cada terminal novo começa com o ambiente desativado, e o python3 que rodou foi o do sistema, que não tem o requests. Como consertar: ative o ambiente (ou chame o Python dele direto, .venv/bin/python baixar.py):

$ source .venv/bin/activate
(.venv) ana@notebook:~/loja$ python baixar.py
Código: 200
Tipo: text/html; charset=utf-8
Tamanho: 577 caracteres

apt install sem sudo

Não é possível adquirir a trava da interface do dpkg (…), você é root?: instalar pacotes do Ubuntu é tarefa de administrador (seção 3). Como consertar: sudo apt install python3-requests. E nunca o contrário: não use sudo pip install; o pip com sudo mexeria justamente na pasta que a PEP 668 protege.

O ModuleNotFoundError é um erro como outro qualquer, e um programa pode se preparar para ele com try e except (aula try e except): em vez de explodir, ele avisa o que falta instalar. O módulo graficos_da_padaria abaixo não existe em lugar nenhum, de propósito.

Missão: rode e veja o ModuleNotFoundError. Depois, coloque o import dentro de um try e, no except ModuleNotFoundError as erro:, mostre Instale com: pip install graficos_da_padaria (o nome do módulo que faltou fica em erro.name).

import graficos_da_padaria

print("Gráficos prontos!")

try:
    import graficos_da_padaria
    print("Gráficos prontos!")
except ModuleNotFoundError as erro:
    print(f"Falta o módulo {erro.name}.")
    print(f"Instale com: pip install {erro.name}")

Referência rápida

Comando	O que faz
`pip --version`	Mostra a versão do `pip` e para qual Python ele instala
`pip install nome`	Baixa do PyPI e instala o pacote (e as dependências)
`pip install "nome==1.2.3"`	Instala uma versão exata
`pip install --upgrade nome` (ou `-U`)	Troca pela versão mais nova
`pip install -r requirements.txt`	Instala tudo o que está na lista do arquivo
`pip list`	Lista os pacotes instalados, com as versões
`pip show nome`	Detalhes de um pacote: versão, local, dependências
`pip freeze`	Lista os pacotes no formato `nome==versão`
`pip freeze > requirements.txt`	Grava essa lista no arquivo
`pip uninstall nome` (`-y` para não perguntar)	Remove o pacote
`python -m pip …`	Qualquer um dos comandos acima, pelo `pip` do Python que está rodando

Sintoma	Causa provável
`error: externally-managed-environment`	`pip install` no Python do sistema (PEP 668): use um ambiente virtual ou o `apt`
`No matching distribution found for …`	Nome errado, ou sem internet (leia as linhas de cima: `Retrying`, `Failed to establish a new connection`)
`ModuleNotFoundError: No module named '…'` depois de instalar	O ambiente virtual não está ativo (o prompt não começa com `(.venv)`)
`você é root?` no `apt`	Faltou o `sudo`
`Comando 'pip' não encontrado`	Falta o pacote `python3-pip` do Ubuntu

Exercícios

1. Instalar

Com o ambiente virtual ativo, complete o comando que instala o pacote requests:

pip requests

2. A lista do projeto

Complete o comando que grava os pacotes do ambiente no arquivo de requisitos:

pip >

3. Instalar a partir da lista

Complete a opção que faz o pip ler o arquivo:

pip install requirements.txt

4. No Ubuntu, fora de qualquer ambiente virtual, pip install requests responde externally-managed-environment. Por quê?

O pacote requests não existe O Python do sistema é cuidado pelo apt, e a PEP 668 impede o pip de mexer nele Falta internet Faltou o sudo antes do pip

5. A Ana pediu só o requests, e o pip instalou cinco pacotes. O que são os outros quatro?

Propagandas que vêm junto Cópias de segurança do requests Dependências: pacotes de que o requests precisa para funcionar Versões antigas do requests

6. Num terminal novo, python3 baixar.py dá ModuleNotFoundError: No module named 'requests', mas ontem a Ana instalou o pacote na .venv. O que falta?

Ativar o ambiente com source .venv/bin/activate Instalar com sudo pip install requests Apagar a .venv Usar --break-system-packages

Missão final: conferir a receita

Missão: a Bia recebeu o requirements.txt da lojinha, e o pip list do ambiente dela está na lista instalados. Complete o programa para mostrar Faltam: rich, ou seja, os nomes do arquivo que não estão em instalados, separados por vírgula.

instalados = ["certifi", "idna", "requests", "urllib3", "charset-normalizer"]
faltam = []

with open("requirements.txt", encoding="utf-8") as arquivo:
    for linha in arquivo:
        nome = linha.strip().split("==")[0]
        # se o nome não estiver em instalados, guarde em faltam

print("Faltam:", ", ".join(faltam))

certifi==2026.7.22
charset-normalizer==3.5.2
idna==3.20
requests==2.34.2
rich==14.1.0
urllib3==2.8.0

instalados = ["certifi", "idna", "requests", "urllib3", "charset-normalizer"]
faltam = []

with open("requirements.txt", encoding="utf-8") as arquivo:
    for linha in arquivo:
        nome = linha.strip().split("==")[0]
        if nome not in instalados:
            faltam.append(nome)

print("Faltam:", ", ".join(faltam))

No computador de verdade, quem faz essa conta é o próprio pip install -r requirements.txt: ele pula o que já está lá ("Requirement already satisfied") e instala só o que falta.

Resumo

Um pacote é código que outra pessoa escreveu; o PyPI (pypi.org) é a loja; o pip é o instalador.
No Ubuntu (e no Debian, e em outras distribuições), pip install no Python do sistema dá externally-managed-environment: é a PEP 668 protegendo as ferramentas do sistema.
As saídas: ambiente virtual (o jeito de todo dia), sudo apt install python3-nome (pacotes famosos, na versão do Ubuntu) e pipx (programas de terminal). Evite --break-system-packages e sudo pip.
No ambiente ativo: pip install, pip list, pip show, pip install --upgrade, pip uninstall.
pip freeze > requirements.txt grava a receita do projeto; pip install -r requirements.txt refaz o ambiente em outro lugar.
ModuleNotFoundError depois de instalar quase sempre é o ambiente desativado: olhe se o prompt começa com (.venv).