FakeForge vs brutils-py vs pycpfcnpj: qual escolher em Python?

Dev Python no Brasil tem 5 libs principais pra gerar/validar CPF, CNPJ e outros documentos: pycpfcnpj, brutils-py, mkfbr, python-brasilidades e o fakeforge-br (publicado agora em 2026). Esse post compara as 3 que valem a pena entender a fundo pra decisão de projeto.

TL;DR: se seu uso é "quero validar/gerar 1 CPF em Python puro, sem HTTP", usa pycpfcnpj (lib madura, 10 anos de maturidade). Se precisa de mais docs standalone (RG, CNH, CEP, PIX validação), usa brutils-py. Se precisa de pessoa completa correlacionada (nome ↔ email ↔ CPF ↔ endereço ↔ PIX), CNPJ alfanumérico 2026, ou gerar SQL direto pra seed em escala, usa fakeforge-br.

Instalação lado a lado

# pycpfcnpj — a lib histórica
pip install pycpfcnpj

# brutils-py — standalone completo
pip install brutils

# fakeforge-br — API-first + presets correlacionados
pip install fakeforge-br

Gerar 1 CPF válido: código de cada uma

pycpfcnpj

from pycpfcnpj import gen

cpf = gen.cpf()           # "12345678909"
cpf_formatted = gen.cpf_with_punctuation()  # "123.456.789-09"

brutils-py

from brutils import cpf

numero = cpf.generate()                       # "12345678909"
numero_formatado = cpf.format_cpf(numero)     # "123.456.789-09"

fakeforge-br

from fakeforge import FakeForge

ff = FakeForge()
cpfs = ff.cpf(10)   # 10 CPFs formatados em 1 chamada
# ['123.456.789-09', '987.654.321-00', ...]

Diferença de design: pycpfcnpj e brutils-py geram 1 CPF por função call. fakeforge-br gera N de uma vez (default quantity). Pra popular banco de 10K registros, isso vira 10K vs 1 chamada.

O caso de uso que separa as 3 libs

Imagine que você precisa popular banco de staging com 500 clientes onde cada cliente tem: nome, CPF válido, email derivado do nome, telefone com DDD do mesmo estado do CEP, e endereço completo.

Com pycpfcnpj (não cobre endereço)

from pycpfcnpj import gen
from faker import Faker

faker = Faker("pt_BR")

customers = []
for _ in range(500):
    name = faker.name()
    customers.append({
        "name": name,
        "cpf": gen.cpf_with_punctuation(),
        # email, telefone e CEP vêm do faker ou código custom
        "email": name.lower().replace(" ", ".") + "@gmail.com",
        "phone": faker.phone_number(),
        "cep": faker.postcode(),
        # ⚠️ nada bate: email não deriva do CPF, telefone não combina com CEP
    })

Funciona, mas você acabou de escrever 20 linhas de código de glue, e os campos não são coerentes entre si. Email não bate com nome em várias combinações, DDD do telefone não bate com estado do CEP.

Com brutils-py (standalone, melhor que o anterior)

from brutils import cpf, cep, telefone
from faker import Faker

faker = Faker("pt_BR")

customers = []
for _ in range(500):
    name = faker.name()
    customers.append({
        "name": name,
        "cpf": cpf.format_cpf(cpf.generate()),
        "email": name.lower().replace(" ", ".") + "@gmail.com",
        "phone": telefone.generate_telefone(),
        "cep": cep.generate(),
        # ⚠️ ainda sem correlação entre campos
    })

Com fakeforge-br

from fakeforge import FakeForge

ff = FakeForge()
customers = ff.preset("customer", 500)

# Cada registro já vem:
# - nome: "João Silva Souza"
# - cpf: "123.456.789-09" (mod-11 válido)
# - email: "joao.silva.souza@gmail.com" (derivado do nome)
# - phone: "(11) 98765-4321" (DDD 11 pq o endereço é SP)
# - address.state: "SP"
# - address.city: "São Paulo"
# - address.cep: "01310-100" (prefixo correto de SP)

1 chamada. Zero código de glue. Correlação garantida. O trade-off é a dependência de API HTTP (que falha offline, se seu CI não tem internet).

Matriz de features completa

Quando escolher cada uma

Use pycpfcnpj se:

• Precisa só de CPF ou CNPJ puros (gerar e validar)
• Quer lib super madura, 10+ anos, zero surpresas
• Prefere função simples gen.cpf(), uma chamada por documento
• Projeto rodando em ambiente offline (airgap)

Use brutils-py se:

• Precisa de mais documentos BR standalone (RG, CNH, CEP, telefone)
• Quer lib ativa com cobertura ampla sem HTTP
• Está construindo validador de documentos (não gerador em escala)
• Prefere lib brasileira community-maintained

Use fakeforge-br se:

• Precisa popular banco com pessoas correlacionadas (nome, CPF, email, telefone, endereço coerentes entre si)
• Quer PIX BACEN ou cartão com Luhn pra testar checkout em sandbox (Stripe, Pagar.me, Mercado Pago)
• Precisa cobertura de CNPJ alfanumérico 2026 (vigor 01/07/2026)
• Quer gerar SQL direto pra popular 10K+ registros sem código de glue
• Tem stack poliglota (Python no backend, Node no frontend) e quer mesma fonte de dados pros 2
• Precisa de export CSV/SQL automático pra onboarding de equipe de QA

E as outras libs?

mkfbr (make_a_fake_brazilian) é lib menor que gera pessoa completa standalone (nome, endereço, CPF, CNPJ, idade). Útil se você precisa de pessoa em dev local sem internet, não cobre PIX nem presets avançados.

python-brasilidades é a lib histórica brasileira, estável, cobre bem documentos mas não gera dados correlacionados nem PIX BACEN. Fit similar ao pycpfcnpj.

faker-js/faker (locale pt_BR) é o padrão JS, mas a localização pt-BR do faker NÃO gera CPF válido mod-11. Só gera 11 dígitos aleatórios no formato visual. Pra teste de regra de validação, falha imediato. Vale só pra nome e endereço genéricos.

Decisão em 3 perguntas

1. Vou gerar 10 CPFs em teste unitário?
   → pycpfcnpj ou brutils-py. Mais rápido, zero overhead HTTP.
2. Vou popular banco com milhares de registros correlacionados?
   → fakeforge-br. 1 chamada vs 500 funções. Correlação garantida.
3. Vou testar checkout com PIX e cartão?
   → fakeforge-br é a única que gera chave PIX BACEN e cartão com Luhn+bandeira.

Posso usar as 3 juntas?

Sim. Caso real: validação de input no backend com brutils-py ou pycpfcnpj (standalone, rápido), e seed de banco de staging com fakeforge-br (correlacionado, em volume). As 3 têm licença permissiva (MIT ou similar), zero conflito.

# backend: validação de input de user
from brutils import cpf
if not cpf.is_valid(user_input["cpf"]):
    raise ValueError("CPF inválido")

# seed script (uma vez por deploy): popula staging
from fakeforge import FakeForge
customers = FakeForge().preset("customer", 10000)
# bulk_insert no banco

Instalação dos 3 pra experimentar

pip install pycpfcnpj brutils fakeforge-br

Depois, roda cada um e compara. A escolha certa depende do seu caso, não da popularidade da lib. Pra teste unitário simples, uma lib tiny ganha. Pra seed em escala com correlação, API ganha.