Módulos e pacotes em Python: import, pip, venv e bibliotecas em linguagem simples

Módulo em Python é um arquivo comum com código, e import é a forma de pegar dele funções e classes. Com módulos se montam pacotes, com pacotes — bibliotecas, e para que as bibliotecas de terceiros de projetos diferentes não se atrapalhem, elas são instaladas em um ambiente virtual venv. Vamos ver a cadeia inteira: o que acontece durante a importação, como um pacote é organizado, como funcionam o pip e o venv e o que são os lazy imports surgidos no Python 3.15.

Módulo, pacote, biblioteca: qual é a diferença

As palavras «biblioteca», «pacote» e «módulo» costumam ser usadas uma pela outra na conversa — isso é normal. O importante é entender que, tecnicamente, o import sempre carrega um módulo ou um pacote, e o pip instala uma distribuição do PyPI, dentro da qual estão os pacotes.

Como o import funciona em Python

Existem várias formas de importação, e todas aparecem em código real:

import math                    # módulo inteiro, uso como math.sqrt
from math import sqrt, pi      # nomes específicos
import datetime as dt          # apelido
from collections import Counter as C

print(math.sqrt(16), sqrt(9), pi)
print(dt.date.today())

Apelidos são consagrados para as grandes bibliotecas: import numpy as np, import pandas as pd. A construção from module import * é melhor evitar: ela polui o espaço de nomes e esconde a origem de cada nome.

O que o import faz de fato

1. Procura o módulo no cache sys.modules. Se ele já foi carregado, apenas o devolve.
2. Se não foi, procura o arquivo nas pastas da lista sys.path: a pasta do script em execução, a biblioteca padrão, o site-packages do ambiente.
3. Executa o arquivo encontrado inteiro, de cima para baixo.
4. Coloca o objeto do módulo no cache e associa-o ao nome.

Daí decorrem duas conclusões práticas. Um segundo import do mesmo módulo é quase gratuito — o código não é executado de novo. E todo o código do nível superior do módulo, incluindo print e cálculos pesados, roda no momento da importação.

import sys
for p in sys.path:
    print(p)
print("math" in sys.modules)

if __name__ == "__main__"

Como a importação executa o arquivo, é preciso um meio de distinguir «fui iniciado como script» de «fui importado». Para isso existe a variável __name__: quando o arquivo é executado diretamente, ela vale "__main__"; na importação — o nome do módulo.

# categorias.py
def adivinhar(titulo: str) -> str:
    return "alimentação" if "café" in titulo.lower() else "outros"

if __name__ == "__main__":
    print(adivinhar("Café da esquina"))   # roda só com python categorias.py

Para um pacote existe uma alternativa: o arquivo __main__.py dentro dele e a execução com python -m gastos.

Módulos padrão do Python

O Python vem «com pilhas incluídas»: centenas de módulos embutidos ficam disponíveis logo de início, sem instalação. Os mais usados:

A lista completa dos módulos da biblioteca padrão fica em sys.stdlib_module_names (Python 3.10+). Ver o que um módulo oferece é possível com dir(math) e help(math).

Pacote próprio: estrutura do projeto

Quando há muitos módulos, eles são reunidos em um pacote. Uma organização comum é o layout com src:

gastos-projeto/
├── pyproject.toml
└── src/
    └── gastos/
        ├── __init__.py
        ├── cli.py
        ├── parsing.py
        ├── categorias.py
        └── relatorio.py

Dentro do pacote, os módulos importam uns aos outros pelo nome do pacote (from gastos.categorias import adivinhar) ou de forma relativa (from .categorias import adivinhar). A importação relativa funciona só dentro do pacote, e não em um arquivo executado diretamente como script.

pip no Python: instalação de bibliotecas

As bibliotecas de terceiros ficam no catálogo PyPI, e são instaladas pelo pip, que acompanha o Python. O mais seguro é chamar o pip através do interpretador — assim a biblioteca certamente entra no mesmo Python com o qual você executa o código.

python -m pip install requests          # instalar
python -m pip install "pandas>=2.3"     # com restrição de versão
python -m pip install --upgrade requests
python -m pip uninstall requests        # remover
python -m pip list                      # lista dos pacotes instalados
python -m pip show requests             # versão e dependências
python -m pip freeze > requirements.txt
python -m pip install -r requirements.txt

No Windows, em vez de python costuma-se usar o lançador py. Se o pip não for encontrado, ele é instalado pelo módulo embutido: python -m ensurepip --upgrade.

Bibliotecas populares do Python

No PyPI há centenas de milhares de pacotes, mas a maioria dos projetos usa uma mesma lista curta. É por ela que vale começar, em vez de procurar algo exótico.

Atenção: o nome para instalar nem sempre coincide com o nome para importar. Instala-se pip install pillow, mas escreve-se from PIL import Image; instala-se opencv-python, mas importa-se cv2. Se o import falha logo após a instalação, confira na documentação do pacote com qual nome ele é importado.

Instalação de bibliotecas no Linux

Nas versões recentes do Debian e do Ubuntu, o comando pip install no Python do sistema termina com o erro externally-managed-environment (PEP 668). Trata-se de uma proteção: o Python do sistema pertence ao gerenciador de pacotes do SO, e o pip não deve quebrá-lo. A solução correta não é --break-system-packages, e sim um ambiente virtual.

venv no Python: ambiente virtual

O ambiente virtual é uma pasta separada com sua própria cópia (um link) do interpretador e seu próprio site-packages. As bibliotecas instaladas nele são visíveis apenas para este projeto. Assim, um projeto pode usar Django 4 e outro, vizinho, — Django 5, sem conflitos.

O módulo venv já vem com o Python, não precisa ser instalado à parte (no Debian/Ubuntu às vezes é preciso o pacote do sistema python3-venv).

# criar o ambiente na pasta .venv
python -m venv .venv

# ativar: Linux e macOS
source .venv/bin/activate
# ativar: Windows PowerShell
.venv\Scripts\Activate.ps1

# agora o pip instala pacotes dentro de .venv
python -m pip install requests
python -c "import sys; print(sys.prefix)"

# sair do ambiente
deactivate

Depois da ativação, no início da linha do terminal aparece (.venv). A pasta do ambiente não vai para o git (inclua .venv/ no .gitignore) e não é transferida entre máquinas — em vez disso, guarda-se a lista de dependências e o ambiente é recriado. Se o PowerShell bloquear o script de ativação, libere-o para o usuário: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

uv e pyproject.toml

Os projetos modernos descrevem as dependências no pyproject.toml. O gerenciador uv, usado no curso, junta a criação do ambiente e a instalação: uv add pandas baixa o pacote, grava-o no pyproject.toml e fixa as versões exatas no uv.lock. Um colega clona o projeto, executa uv sync e recebe exatamente o mesmo ambiente.

[project]
name = "gastos"
version = "0.1.0"
requires-python = ">=3.15"
dependencies = [
    "pandas>=2.3",
]

[project.scripts]
gastos = "gastos.cli:main"

Lazy imports no Python 3.15 (PEP 810)

A principal novidade de 3.15 neste tema é a palavra-chave lazy. Bibliotecas pesadas carregam devagar: na medição do curso, em uma imagem python:3.15-slim, um import pandas comum levou cerca de 415 ms, e lazy import pandas — cerca de 13 ms. Para uma utilidade de linha de comando que é executada para mostrar o --help, a diferença é enorme.

lazy import pandas as pd
lazy from gastos.relatorio import montar

def main() -> None:
    ...
    df = pd.read_csv(path)   # carregamento real do pandas — só aqui

No lugar do módulo é colocado um objeto-proxy (types.LazyImportType), e a importação de verdade acontece no primeiro acesso ao nome. Se ele nunca for usado, o tempo não é gasto.

Limitações do lazy import

• Permitido apenas no nível superior do módulo: dentro de função, classe ou try/except — SyntaxError.
• lazy from x import * é proibido.
• ModuleNotFoundError aparece não na inicialização, mas no primeiro uso.
• Os efeitos colaterais do módulo (registro de plugins etc.) são deslocados no tempo.

Tornar ativas todas as importações lazy de uma vez é possível com a opção -X lazy_imports=all ou com a variável PYTHON_LAZY_IMPORTS=all; exceções são definidas por sys.set_lazy_imports_filter(). Para código que precisa rodar em versões antigas existe a variável do módulo __lazy_modules__ = ["pandas"]: o 3.15 torna lazy os módulos listados, e as versões antigas simplesmente fazem um import comum. Onde o tempo é gasto na inicialização mostra o comando python -X importtime -c "import pandas". Ganham sobretudo programas que são iniciados com frequência e por pouco tempo; um servidor de longa duração quase não se beneficia.

Erros típicos

• ModuleNotFoundError: No module named 'requests' — a biblioteca foi instalada em outro Python, ou o ambiente não está ativado. Confira com python -m pip show requests usando o mesmo interpretador.
• O arquivo do projeto se chama json.py, random.py ou csv.py — a pasta do script fica em primeiro lugar no sys.path e sobrepõe o módulo padrão. A partir do Python 3.13 o erro sugere «consider renaming». Renomeie o arquivo e apague o __pycache__.
• Importação circular: a.py importa b.py, e este importa a.py. Mova o código comum para um terceiro módulo ou faça a importação dentro de uma função.
• O pip foi chamado dentro do interpretador (>>> pip install) — isso gera SyntaxError. Os comandos do pip são executados no terminal.

Resumo

Módulo é um arquivo, pacote — uma pasta de módulos, biblioteca — um conjunto pronto deles; o import procura o módulo no cache e no sys.path e executa-o uma única vez. As bibliotecas de terceiros devem ser instaladas com pip ou uv somente em um ambiente virtual venv — assim os projetos não atrapalham uns aos outros, e o ambiente é fácil de reproduzir. No curso de Python este tema é praticado: o controle de gastos vira um pacote com dependências e inicia rapidamente graças aos lazy imports.