Módulos e imports em Python: import, from-import, pip e pacotes

Um arquivo é um módulo

Quando seu código Python cresce além de um único script, você vai querer dividir em vários arquivos. O sistema de módulos do Python é simples: qualquer arquivo .py é automaticamente um módulo, importável pelo nome.

Digamos que você tem um arquivo util.py:

# util.py
def greet(name):
    return f"Hello, {name}"

PI = 3.14159

De outro arquivo no mesmo diretório — main.py — você pode usar:

# main.py
import util

print(util.greet("Ada"))
print(util.PI)

Rode python3 main.py e o Python acha util.py, executa uma vez e expõe tudo definido no nível de topo (funções, variáveis, classes) como atributos do módulo util.

As três formas de import

Importe o módulo inteiro. Coisas de dentro são acessadas pelo nome do módulo:

Importe nomes específicos. Ficam disponíveis diretamente:

Importe com alias. Útil quando o nome do módulo é longo ou quando dois módulos compartilham nome:

import numpy as np
import pandas as pd

# Now use np.array(...), pd.DataFrame(...), etc.

Existe uma quarta forma, from math import *, que puxa tudo para seu namespace. Evite fora de experimentação no REPL — torna impossível dizer de onde um nome veio, e cria colisões silenciosas.

Quando imports rodam

O Python executa o código de topo do módulo importado uma vez, a primeira vez que é importado num dado programa. Imports subsequentes do mesmo módulo retornam a versão já carregada. Então isto:

# setup.py
print("setup module loading...")
VALUE = 42

# main.py
import setup
import setup  # imported twice — but "loading" only prints once
print(setup.VALUE)

Só imprime "setup module loading..." uma vez. Isso importa: se você colocar efeitos colaterais (como abrir um arquivo ou imprimir) no nível de topo do módulo, eles acontecem no tempo de import, o que geralmente não é o que você quer. Coloque dentro de funções.

A biblioteca padrão

O Python vem com uma grande biblioteca padrão de módulos. Você já viu alguns. Alguns que vai usar constantemente:

• math — sqrt, sin, log, constantes como pi e e.
• random — números aleatórios, escolhas, embaralhamento.
• datetime — datas e horas.
• json — ler/escrever JSON.
• os, os.path — caminhos e operações de sistema de arquivos.
• pathlib — manipulação moderna de paths, muitas vezes mais gentil do que os.path.
• re — expressões regulares.
• collections — tipos especializados de coleção (Counter, defaultdict, deque, etc.).
• itertools, functools — helpers de iterador e função.
• csv — ler e escrever arquivos CSV.

A biblioteca padrão já está instalada — nada para pip install.

Pacotes de terceiros e pip

Para qualquer coisa que a biblioteca padrão não cobre, o Python Package Index (PyPI) hospeda centenas de milhares de pacotes. Instale com pip:

pip install requests
pip install pandas
pip install --upgrade requests
pip uninstall requests

Uma vez instalados, eles importam como qualquer outra coisa:

import requests

response = requests.get("https://api.example.com/data")
print(response.status_code)

Algumas dicas sobre gerenciar isso com sanidade:

Use ambientes virtuais

Instalar tudo globalmente leva à dor. Projetos diferentes precisam de versões diferentes; alguns pacotes dependem de versões específicas do Python; instalações globais exigem direitos de admin em alguns sistemas. Um ambiente virtual é uma instalação Python isolada para um projeto:

python3 -m venv .venv
source .venv/bin/activate    # macOS/Linux
.venv\Scripts\activate       # Windows

pip install requests

Enquanto o venv está ativado, pip instala na pasta do projeto, não no sistema. Desative com deactivate quando terminar.

Fixe suas dependências

Salve a lista de pacotes instalados para que outros (inclusive você no futuro) possam recriar o mesmo ambiente:

pip freeze > requirements.txt

Depois mais tarde:

pip install -r requirements.txt

Ferramentas como Poetry, pipenv e uv lidam com isso de forma mais ergonômica, mas o fluxo pip + requirements.txt ainda é ok para aprender.

Escrevendo seus próprios módulos

Quando você tem funções que quer reusar entre arquivos, coloque no seu próprio módulo. Convenções de nome:

• Nomes de arquivo devem ser lower_snake_case.py.
• Funções e variáveis de nível de módulo também lower_snake_case.
• Classes usam PascalCase.

# shopping.py
PRICES = {"apple": 0.50, "bread": 2.00}

def total(items):
    return sum(PRICES[item] for item in items)

# main.py
from shopping import total, PRICES

print(total(["apple", "bread"]))
print(PRICES)

Se dois arquivos na mesma pasta se importam mutuamente, você pode acidentalmente criar um import circular. A correção usual é mover o código compartilhado para um terceiro arquivo que os dois importam.

Pacotes: pastas de módulos

Quando você tem mais do que um punhado de módulos, agrupe num pacote — uma pasta com um arquivo __init__.py dentro:

myproject/
├── main.py
└── utils/
    ├── __init__.py
    ├── text.py
    └── numbers.py

Aí:

from utils.text import slugify
from utils import numbers

print(slugify("Hello, World"))
print(numbers.mean([1, 2, 3]))

O __init__.py pode ser vazio; a presença dele é o que faz utils ser um pacote. O Python moderno também suporta "namespace packages" sem __init__.py, mas para começar, a versão explícita é mais clara.

Uma lista curta quando imports quebram

• "ModuleNotFoundError: No module named X". Ou o pacote não está instalado, ou você está rodando Python de um interpretador diferente do que rodou pip install. Num venv, garanta que o venv está ativado.
• "ImportError: cannot import name Y from X". O módulo existe, mas o nome que você pediu não está lá. Procure typos e olhe o conteúdo real do módulo.
• "Circular import". Dois módulos se importam. Mova o código compartilhado para um terceiro módulo.

Próxima: instalando pacotes de terceiros

Seus próprios módulos te levam longe, mas a maioria dos projetos reais também puxa bibliotecas do PyPI — requests, pandas, um framework de teste. A próxima página cobre pip, como instalar pacotes de forma limpa e como registrar do que seu projeto depende.