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

URL: https://skillaria.top/pt/guides/python/modulos-pacotes-python-venv

Módulo em Python é um arquivo .py, pacote é uma pasta de módulos, e biblioteca é um conjunto de pacotes; tudo isso é conectado pelo comando import. As bibliotecas de terceiros são instaladas com pip (ou uv) em um ambiente virtual venv — uma pasta isolada com o próprio interpretador e pacotes de um projeto, para que as versões de projetos diferentes não entrem em conflito.

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

| Conceito | O que é | Exemplo |
| --- | --- | --- |

| Módulo | Um arquivo `.py`; o nome do módulo é o nome do arquivo sem a extensão | `categorias.py` → `import categorias` |

| Pacote | Uma pasta com módulos e o arquivo `__init__.py` | `gastos/relatorio.py` → `from gastos.relatorio import montar` |

| Biblioteca | Um conjunto pronto de módulos e pacotes para alguma tarefa | `requests`, `pandas`, a `pathlib` padrão |

| Distribuição (pacote do PyPI) | Um arquivo que o pip instala | `pip install requests` |

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:

| Módulo | Para que serve |
| --- | --- |

| `os`, `sys`, `pathlib`, `shutil` | Sistema, caminhos, arquivos |

| `json`, `csv`, `pickle` | Formatos de dados |

| `datetime`, `time`, `calendar` | Data e hora |

| `math`, `random`, `statistics`, `fractions` | Números |

| `re`, `string` | Trabalho com texto |

| `collections`, `itertools`, `functools` | Estruturas de dados e iteradores |

| `logging`, `argparse`, `subprocess` | Logs, argumentos de linha de comando, execução de programas |

| `asyncio`, `threading` | Assincronia e threads |

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.

| Tarefa | Bibliotecas |
| --- | --- |

| Requisições HTTP e APIs | `requests`, `httpx` |

| Análise de dados e tabelas | `pandas`, `numpy` |

| Gráficos | `matplotlib` |

| Serviços web | `fastapi`, `django`, `flask` |

| Testes | `pytest` |

| Imagens | `pillow` (importada como `PIL`) |

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.

## FAQ

**Preciso criar um venv para cada projeto?**

Sim, é uma boa prática: cada projeto tem suas versões de bibliotecas, e um ambiente separado evita conflitos e não polui o Python do sistema.

**Qual a diferença entre pip e uv?**

O pip apenas instala pacotes; o uv também cria o ambiente, registra as dependências no pyproject.toml e fixa as versões exatas num arquivo de lock. Além disso, é bem mais rápido.

**Como ver a lista de bibliotecas instaladas no Python?**

Execute python -m pip list no ambiente desejado; o pip freeze mostra a mesma lista no formato do requirements.txt.

**Onde ficam guardados os módulos instalados?**

Na pasta site-packages do ambiente atual; o caminho de um módulo mostra o atributo __file__, por exemplo: import requests; print(requests.__file__).

**Posso copiar a pasta venv para outro computador?**

Não: o ambiente está ligado aos caminhos e ao interpretador da máquina. Transfere-se a lista de dependências, e o ambiente é criado de novo.


---
Source: Skillaria.Top (https://skillaria.top)