GitHub - LacusSolutions/br-utils-py: Python utility functions and resources for Brazilian-related data.

🚀 Full support for the new alphanumeric CNPJ format.

🌎 Acessar documentação em português

A Python toolkit to handle the main operations with Brazilian-related data: CPF (Individual's Taxpayer ID) and CNPJ (Business Tax ID). It provides a top-level BrUtils wrapper around cpf-utils and cnpj-utils, exposing all bundled resources under a unified import path.

Python Support


Passing ✔	Passing ✔	Passing ✔	Passing ✔	Passing ✔

Features

✅ Unified top-level API: One BrUtils instance with cpf and cnpj domain accessors
✅ Bundled domains: cpf-utils and cnpj-utils installed together
✅ Alphanumeric CNPJ: Full support for the new alphanumeric CNPJ format (introduced in 2026)
✅ Configurable defaults: Set formatter, generator, and (for CNPJ) validator options on each domain instance
✅ Per-call overrides: Override any component option for a single method call
✅ Dual API style: Top-level façade (BrUtils), domain aggregators (CpfUtils, CnpjUtils), standalone components, and functional helpers
✅ Shared submodules: CPF symbols under br_utils.cpf; CNPJ symbols under br_utils.cnpj
✅ Typed error handling: Dedicated exception hierarchies from bundled packages (TypeError / Exception model from cpf-utils and cnpj-utils v2)

Installation

$ pip install br-utilities

This installs br-utilities together with cpf-utils and cnpj-utils (which in turn pull in the CPF and CNPJ component packages). You do not need separate pip install calls for the domain packages when using br-utilities.

Import

Pick the API that fits your use case.

Top-level façade and domain singletons:

from br_utils import BrUtils, br_utils, CpfUtils, CnpjUtils, cpf_utils, cnpj_utils

CPF components and helpers (br_utils.cpf):

from br_utils.cpf import (
    CpfFormatter,
    CpfFormatterOptions,
    CpfGenerator,
    CpfGeneratorOptions,
    CpfValidator,
    cpf_fmt,
    cpf_gen,
    cpf_val,
)

CNPJ components and helpers (br_utils.cnpj):

from br_utils.cnpj import (
    CnpjFormatter,
    CnpjFormatterOptions,
    CnpjGenerator,
    CnpjGeneratorOptions,
    CnpjValidator,
    CnpjValidatorOptions,
    cnpj_fmt,
    cnpj_gen,
    cnpj_val,
)

Functional helpers (cpf_fmt, cnpj_fmt, and related symbols) are not re-exported from the package root — import them from br_utils.cpf or br_utils.cnpj.

Quick start

With br_utils (default singleton):

from br_utils import br_utils

cpf = '11144477735'
cnpj = '03603568000195'

br_utils.cpf.format(cpf)      # '111.444.777-35'
br_utils.cpf.is_valid(cpf)    # True
br_utils.cpf.generate()       # e.g. '11508890048'

br_utils.cnpj.format(cnpj)    # '03.603.568/0001-95'
br_utils.cnpj.is_valid(cnpj)  # True
br_utils.cnpj.generate()      # e.g. '1GJTR3J3XSSA96'

With domain aggregators:

from br_utils import CpfUtils, CnpjUtils

cpf = '11144477735'
cnpj = '03603568000195'

CpfUtils().format(cpf)      # '111.444.777-35'
CnpjUtils().format(cnpj)    # '03.603.568/0001-95'
CpfUtils().is_valid(cpf)    # True
CnpjUtils().is_valid(cnpj)  # True

With functional helpers:

from br_utils.cpf import cpf_fmt, cpf_val
from br_utils.cnpj import cnpj_fmt, cnpj_val

cpf = '11144477735'
cnpj = '03603568000195'

cpf_fmt(cpf)     # '111.444.777-35'
cpf_val(cpf)     # True
cnpj_fmt(cnpj)   # '03.603.568/0001-95'
cnpj_val(cnpj)   # True

Usage

You can work in four equivalent ways:

br_utils — pre-built BrUtils singleton with shared defaults across both CPF and CNPJ domains.
BrUtils — create your own instance with custom default CPF and CNPJ settings.
Domain aggregators — CpfUtils and CnpjUtils directly (same classes used internally by BrUtils).
Component classes and functional helpers — CpfFormatter, CnpjGenerator, cpf_fmt(), cnpj_gen(), and related symbols.

All approaches expose the same options and behavior within each domain. For full option tables and component-specific details, see the README of each bundled package.

`br_utils` (default instance)

The module-level br_utils is a pre-built BrUtils instance. Use it for quick one-off calls:

cpf: Access the CPF utilities (CpfUtils). Use br_utils.cpf.format(), br_utils.cpf.generate(), br_utils.cpf.is_valid() with the same options as in cpf-utils.
cnpj: Access the CNPJ utilities (CnpjUtils). Use br_utils.cnpj.format(), br_utils.cnpj.generate(), br_utils.cnpj.is_valid() with the same options as in cnpj-utils.

`BrUtils` (class)

For custom default CPF or CNPJ utils, create your own instance:

from br_utils import BrUtils

utils = BrUtils(
    cpf={
        'formatter': {'hidden': True, 'hidden_key': '#'},
        'generator': {'format': True},
    },
    cnpj={
        'formatter': {'hidden': True},
        'generator': {'type': 'numeric', 'format': True},
        'validator': {'type': 'numeric'},
    },
)

utils.cpf.format('11144477735')        # '111.###.###-##'
utils.cpf.generate()                   # e.g. '005.265.352-88'
utils.cnpj.format('03603568000195')    # '03.603.***/****-**'
utils.cnpj.generate()                  # e.g. '73.008.535/0005-06'

# Access internal domain instances
utils.cpf    # CpfUtils
utils.cnpj   # CnpjUtils

__init__(…): All arguments are keyword-only and optional.
- cpf / cnpj: A pre-built CpfUtils / CnpjUtils instance or a configuration mapping spread into the corresponding utils constructor. Within that mapping, each resource key (formatter, generator, and validator for CNPJ) accepts either an options object or a mapping of option values.
- cpf_formatter, cpf_generator, cnpj_formatter, cnpj_generator, cnpj_validator: Flat convenience arguments when only individual components need customization. They are ignored when the corresponding cpf or cnpj argument is provided.
cpf, cnpj: Properties with getters and setters for the domain utils instances. Setters accept a utils instance, a configuration mapping, or None to reset to defaults (replaces the entire instance; does not merge).

Flat constructor options (alternative to nested cpf / cnpj mappings):

from br_utils import BrUtils
from br_utils.cpf import CpfFormatterOptions, CpfGeneratorOptions
from br_utils.cnpj import CnpjFormatterOptions, CnpjGeneratorOptions, CnpjValidatorOptions

utils = BrUtils(
    cpf_formatter=CpfFormatterOptions(hidden=True, hidden_key='#'),
    cpf_generator=CpfGeneratorOptions(format=True),
    cnpj_formatter=CnpjFormatterOptions(hidden=True, hidden_key='#'),
    cnpj_generator=CnpjGeneratorOptions(format=True, type='numeric'),
    cnpj_validator=CnpjValidatorOptions(type='numeric'),
)

Instance defaults and per-call overrides

from br_utils import BrUtils

utils = BrUtils(
    cpf={
        'formatter': {'hidden': True, 'hidden_key': '#'},
        'generator': {'format': True},
    },
    cnpj={
        'formatter': {'hidden': True, 'hidden_key': '#'},
        'generator': {'format': True},
        'validator': {'type': 'numeric'},
    },
)

cpf = '11144477735'
cnpj = '03603568000195'

utils.cpf.format(cpf)                  # '111.###.###-##'
utils.cpf.format(cpf, hidden=False)    # '111.444.777-35'
utils.cpf.generate(format=False)       # e.g. '58450042259'

utils.cnpj.format(cnpj)                  # '03.603.###/####-##'
utils.cnpj.format(cnpj, hidden=False)    # '03.603.568/0001-95'
utils.cnpj.is_valid('1QB5UKALPYFP59')    # False
utils.cnpj.is_valid(                     # True
    '1QB5UKALPYFP59',
    type='alphanumeric',
)

Passing a CnpjFormatterOptions, CnpjGeneratorOptions, or CnpjValidatorOptions instance to the BrUtils constructor stores that object by reference — mutating it later affects subsequent calls with no per-call override.

CPF operations

CPF methods are accessed via utils.cpf, CpfUtils, or the cpf_*() helpers from br_utils.cpf. CPF uses the v2 API from cpf-utils: str or sequence input for format() / is_valid(), mapping or keyword overrides per call, and structured exceptions.

Formatting (`format` / `cpf_fmt`)

Option	Type	Default	Description
`hidden`	`bool`	`False`	When `True`, mask digits in `hidden_start`–`hidden_end` with `hidden_key`
`hidden_key`	`str`	`'*'`	Character(s) used to replace masked digits
`hidden_start`	`int`	`3`	Start index (0–10, inclusive) of the range to hide
`hidden_end`	`int`	`10`	End index (0–10, inclusive) of the range to hide
`dot_key`	`str`	`'.'`	Dot delimiter (e.g. in `123.456.789`)
`dash_key`	`str`	`'-'`	Dash delimiter (e.g. before check digits `…-09`)
`escape`	`bool`	`False`	When `True`, escape HTML special characters in the result
`encode`	`bool`	`False`	When `True`, URL-encode the result (similar to JavaScript `encodeURIComponent`)
`on_fail`	`Callable`	returns `''`	Callback when sanitized input length ≠ 11; return value is used as result

Default on_fail returns an empty string. Invalid length does not throw from format().

from br_utils import br_utils
from br_utils.cpf import cpf_fmt

cpf = '11144477735'

br_utils.cpf.format(cpf)                                        # '111.444.777-35'
br_utils.cpf.format(cpf, hidden=True, hidden_key='#')           # '111.###.###-##'
br_utils.cpf.format(cpf, dot_key='', dash_key='_')              # '111444777_35'

cpf_fmt(cpf, hidden=True)                                       # '111.***.***-**'

Generation (`generate` / `cpf_gen`)

Option	Type	Default	Description
`format`	`bool`	`False`	When `True`, return the generated CPF in standard format (`000.000.000-00`)
`prefix`	`str`	`''`	Partial start string (0–9 digits). Non-digits are stripped; missing characters are generated and check digits computed. Prefixes longer than 9 digits are truncated silently.

Prefix rules: the base (first 9 digits) cannot be all zeros; 9 repeated digits (e.g. 999999999) are not allowed.

from br_utils import br_utils
from br_utils.cpf import cpf_gen

br_utils.cpf.generate()                      # e.g. '11508890048'
br_utils.cpf.generate(format=True)             # e.g. '661.134.831-00'
br_utils.cpf.generate(prefix='123456789')    # '12345678909'
cpf_gen(prefix='123456789', format=True)     # '123.456.789-09'

Validation (`is_valid` / `cpf_val`)

Accepts formatted or unformatted CPF strings (or a sequence of strings). Returns True or False without throwing for invalid CPF. No validator options exist.

from br_utils import br_utils
from br_utils.cpf import cpf_val

br_utils.cpf.is_valid('11144477735')      # True
br_utils.cpf.is_valid('111.444.777-35')   # True
br_utils.cpf.is_valid('11144477736')      # False
cpf_val('11144477735')                    # True

CNPJ operations

CNPJ methods are accessed via utils.cnpj, CnpjUtils, or the cnpj_*() helpers from br_utils.cnpj. CNPJ uses the v2 API from cnpj-utils.

Formatting (`format` / `cnpj_fmt`)

Option	Type	Default	Description
`hidden`	`bool`	`False`	When `True`, mask characters in `hidden_start`–`hidden_end` with `hidden_key`
`hidden_key`	`str`	`'*'`	Character(s) used to replace masked characters
`hidden_start`	`int`	`5`	Start index (0–13, inclusive) of the range to hide
`hidden_end`	`int`	`13`	End index (0–13, inclusive) of the range to hide
`dot_key`	`str`	`'.'`	Dot delimiter (e.g. in `12.345.678`)
`slash_key`	`str`	`'/'`	Slash delimiter (e.g. before branch `…/0001-90`)
`dash_key`	`str`	`'-'`	Dash delimiter (e.g. before check digits `…-90`)
`escape`	`bool`	`False`	When `True`, escape HTML special characters in the result
`encode`	`bool`	`False`	When `True`, URL-encode the result (similar to JavaScript `encodeURIComponent`)
`on_fail`	`Callable`	returns `''`	Callback when sanitized input length ≠ 14; return value is used as result

Default on_fail returns an empty string. Wrong input types throw CnpjFormatterInputTypeError.

from br_utils import br_utils
from br_utils.cnpj import cnpj_fmt

cnpj = '03603568000195'

br_utils.cnpj.format(cnpj)              # '03.603.568/0001-95'
br_utils.cnpj.format('12ABC34500DE99')   # '12.ABC.345/00DE-99'
br_utils.cnpj.format(                     # '03.603.###/####-##'
    cnpj,
    hidden=True,
    hidden_key='#',
)
br_utils.cnpj.format(                     # '03603568|0001_95'
    cnpj,
    dot_key='',
    slash_key='|',
    dash_key='_',
)

cnpj_fmt(cnpj)   # '03.603.568/0001-95'

Generation (`generate` / `cnpj_gen`)

Option	Type	Default	Description
`format`	`bool`	`False`	When `True`, return the generated CNPJ in standard format (`00.000.000/0000-00`)
`prefix`	`str`	`''`	Partial start string (0–12 alphanumeric chars). Missing characters are generated and check digits computed.
`type`	`'numeric'` \| `'alphabetic'` \| `'alphanumeric'`	`'alphanumeric'`	Character set for the randomly generated part. Check digits are always numeric.

Prefix rules: base ID (first 8 chars) and branch ID (chars 9–12) cannot be all zeros; 12 repeated digits (e.g. 111111111111) are also not allowed.

from br_utils import br_utils
from br_utils.cnpj import cnpj_gen

br_utils.cnpj.generate()               # e.g. '1GJTR3J3XSSA96'
br_utils.cnpj.generate(format=True)    # e.g. 'V1.J0V.8WE/DVZ7-50'
br_utils.cnpj.generate(                # e.g. '12345678855883'
    prefix='12345678',
    type='numeric',
)
cnpj_gen(type='numeric')               # e.g. '65453043000178'

Validation (`is_valid` / `cnpj_val`)

Option	Type	Default	Description
`case_sensitive`	`bool`	`True`	When `False`, lowercase letters are accepted for alphanumeric CNPJ (input is uppercased before validation).
`type`	`'numeric'` \| `'alphanumeric'`	`'alphanumeric'`	`'numeric'`: only digits (0–9); `'alphanumeric'`: digits and letters (0–9, A–Z).

from br_utils import br_utils
from br_utils.cnpj import cnpj_val

br_utils.cnpj.is_valid('98765432000198')   # True
br_utils.cnpj.is_valid('98765432000199')   # False
br_utils.cnpj.is_valid('1QB5UKALPYFP59')   # True
br_utils.cnpj.is_valid('1QB5UKALpyfp59')   # False
br_utils.cnpj.is_valid(                     # True
    '1QB5UKALpyfp59',
    case_sensitive=False,
)
br_utils.cnpj.is_valid(                     # False
    '1QB5UKALPYFP59',
    type='numeric',
)

cnpj_val('98765432000198')                         # True
cnpj_val('1QB5UKALpyfp59', case_sensitive=False)   # True
cnpj_val('1QB5UKALPYFP59', type='numeric')         # False

Invalid CNPJ returns False without throwing. Wrong input types throw CnpjValidatorInputTypeError.

Domain aggregators (standalone)

Use CpfUtils or CnpjUtils directly when you only need one domain:

from br_utils import CpfUtils, CnpjUtils

cpf_utils = CpfUtils(
    formatter={'hidden': True},
    generator={'format': True},
)

cnpj_utils = CnpjUtils(
    formatter={'hidden': True},
    generator={'format': True},
    validator={'type': 'numeric'},
)

cpf_utils.format('11144477735')       # '111.***.***-**'
cnpj_utils.format('03603568000195')   # '03.603.***/****-**'

The module-level cpf_utils and cnpj_utils singletons (re-exported from the dependencies) are also available from the package root:

from br_utils import cpf_utils, cnpj_utils

cpf_utils.format('11144477735')   # '111.444.777-35'
cnpj_utils.format('03603568000195')   # '03.603.568/0001-95'

Accessing components

Each domain aggregator exposes its internal formatter, generator, and validator:

from br_utils import BrUtils

utils = BrUtils()

utils.cpf.formatter.format('11144477735', hidden=True)   # '111.***.***-**'
utils.cpf.generator.generate(format=True)                # e.g. '545.507.690-68'
utils.cpf.validator.is_valid('11144477735')              # True

utils.cnpj.formatter.format('12ABC34500DE99')    # '12.ABC.345/00DE-99'
utils.cnpj.generator.generate(format=True)       # e.g. '8O.BE5.2KL/UI0Y-06'
utils.cnpj.validator.is_valid('03603568000195')  # True

Mixing styles

Use BrUtils where a shared configuration helps, and standalone components or helpers elsewhere — they are the same underlying classes:

from br_utils import BrUtils
from br_utils.cnpj import CnpjFormatter
from br_utils.cpf import cpf_fmt
from br_utils.cnpj import cnpj_val

utils = BrUtils(cnpj={'validator': {'type': 'numeric'}})

# Via façade
utils.cpf.format('11144477735')   # '111.444.777-35'

# Via component returned by the façade
utils.cnpj.formatter.format('12ABC34500DE99')   # '12.ABC.345/00DE-99'

# Via a separate component instance
CnpjFormatter().format('03603568000195')   # '03.603.568/0001-95'

# Via functional helpers
cpf_fmt('11144477735')           # '111.444.777-35'
cnpj_val('98.765.432/0001-98')   # True

API

Exports

Package root (br_utils):

br_utils: Pre-built BrUtils instance with cpf and cnpj.
BrUtils: Class to create an instance with optional default CPF and CNPJ utils settings.
CpfUtils, cpf_utils: CPF domain aggregator and its default singleton (from cpf-utils).
CnpjUtils, cnpj_utils: CNPJ domain aggregator and its default singleton (from cnpj-utils).

br_utils.cpf — all exports from cpf-utils (e.g. cpf_fmt, cpf_gen, cpf_val, formatter/generator/validator classes, options, exceptions).

br_utils.cnpj — all exports from cnpj-utils (e.g. cnpj_fmt, cnpj_gen, cnpj_val, formatter/generator/validator classes, options, exceptions).

Errors & Exceptions

BrUtils does not define its own exception types; it propagates errors from the bundled packages:

CPF formatting: CpfFormatterInputTypeError, CpfFormatterOptionsTypeError, CpfFormatterOptionsHiddenRangeInvalidException, CpfFormatterOptionsForbiddenKeyCharacterException, and related classes.
CPF generation: CpfGeneratorOptionsTypeError, CpfGeneratorOptionPrefixInvalidException, and related classes.
CPF validation: CpfValidatorInputTypeError and related classes.
CNPJ formatting: CnpjFormatterInputTypeError, CnpjFormatterOptionsTypeError, CnpjFormatterOptionsHiddenRangeInvalidException, CnpjFormatterOptionsForbiddenKeyCharacterException, and related classes.
CNPJ generation: CnpjGeneratorOptionsTypeError, CnpjGeneratorOptionPrefixInvalidException, CnpjGeneratorOptionTypeInvalidException, and related classes.
CNPJ validation: CnpjValidatorInputTypeError, CnpjValidatorOptionsTypeError, CnpjValidatorOptionTypeInvalidException, and related classes.

Invalid option types are TypeError subclasses; invalid option values are Exception subclasses. CPF and CNPJ validation failures return False. Formatting length failures are handled by on_fail (default: return '').

from br_utils import BrUtils
from br_utils.cnpj import CnpjFormatterInputTypeError, CnpjValidatorInputTypeError

br_utils = BrUtils()

try:
    br_utils.cnpj.format(12345)   # raises CnpjFormatterInputTypeError
except CnpjFormatterInputTypeError as e:
    print(e)

try:
    br_utils.cnpj.is_valid(12345678000198)   # raises CnpjValidatorInputTypeError
except CnpjValidatorInputTypeError as e:
    print(e)

cpf_out = br_utils.cpf.format(     # 'invalid'
    'short',
    on_fail=lambda value, exception=None: 'invalid',
)
cnpj_out = br_utils.cnpj.format(   # 'invalid'
    'short',
    on_fail=lambda value, exception=None: 'invalid',
)

For exhaustive exception lists and edge-case behavior, see each bundled package README.

Bundled packages

Package	Main resources	README
`cpf-utils`	`CpfUtils`, `CpfFormatter`, `CpfGenerator`, `CpfValidator`, `cpf_fmt()`, `cpf_gen()`, `cpf_val()`	docs
`cnpj-utils`	`CnpjUtils`, `CnpjFormatter`, `CnpjGenerator`, `CnpjValidator`, `cnpj_fmt()`, `cnpj_gen()`, `cnpj_val()`	docs

All CPF symbols are available under br_utils.cpf; all CNPJ symbols under br_utils.cnpj. Interactive demos: CPF and CNPJ.

Contribution & Support

We welcome contributions! Please see our Contributing Guidelines for details. If you find this project helpful, please consider:

⭐ Starring the repository
🤝 Contributing to the codebase
💡 Suggesting new features
🐛 Reporting bugs

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG for a list of changes and version history.

Made with ❤️ by Lacus Solutions

Name		Name	Last commit message	Last commit date
.github		.github
context		context
packages		packages
scripts		scripts
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.ruff.toml		.ruff.toml
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
README.pt.md		README.pt.md
require		require
requirements-dev.txt		requirements-dev.txt
run		run
setup.cfg		setup.cfg

Navigation Menu

Repository files navigation

Python Support

Features

Installation

Import

Quick start

Usage

`br_utils` (default instance)

`BrUtils` (class)

Instance defaults and per-call overrides

CPF operations

Formatting (`format` / `cpf_fmt`)

Generation (`generate` / `cpf_gen`)

Validation (`is_valid` / `cpf_val`)

CNPJ operations

Formatting (`format` / `cnpj_fmt`)

Generation (`generate` / `cnpj_gen`)

Validation (`is_valid` / `cnpj_val`)

Domain aggregators (standalone)

Accessing components

Mixing styles

API

Exports

Errors & Exceptions

Bundled packages

Contribution & Support

License

Changelog

About

Releases

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Python Support

Features

Installation

Import

Quick start

Usage

br_utils (default instance)

BrUtils (class)

Instance defaults and per-call overrides

CPF operations

Formatting (format / cpf_fmt)

Generation (generate / cpf_gen)

Validation (is_valid / cpf_val)

CNPJ operations

Formatting (format / cnpj_fmt)

Generation (generate / cnpj_gen)

Validation (is_valid / cnpj_val)

Domain aggregators (standalone)

Accessing components

Mixing styles

API

Exports

Errors & Exceptions

Bundled packages

Contribution & Support

License

Changelog

About

Topics

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Used by

Contributors

Languages

`br_utils` (default instance)

`BrUtils` (class)

Formatting (`format` / `cpf_fmt`)

Generation (`generate` / `cpf_gen`)

Validation (`is_valid` / `cpf_val`)

Formatting (`format` / `cnpj_fmt`)

Generation (`generate` / `cnpj_gen`)

Validation (`is_valid` / `cnpj_val`)