Codice fiscale in Python

Overview

python-codicefiscale computes a codice fiscale from last name, first name, gender, birth date and birthplace, and also works the other way round. Decoding returns the gender, birth date, birthplace (name, province, code), possible first names, every omocodia variant and the raw segments of the code. Two functions check whether a code is valid and whether it is an omocode.

The library detects the birthplace code from the name of an Italian municipality or a foreign country, and accepts several birth date formats. According to the README, its data is updated weekly from the ANPR source. A command-line interface is also available.

Highlights

• Encoding and decoding of the codice fiscale, plus the is_valid and is_omocode functions.
• Omocodia support: decoding lists the possible variants of the code.
• Automatic detection of the birthplace code (Italian municipality or foreign country) from its name.
• Data updated once a week from ANPR data, according to the README.
• Command-line interface: python -m codicefiscale with the encode and decode subcommands.

Who it is for

For Python developers who need to compute, check or parse a codice fiscale, for example to recover the birth date and birthplace it encodes.

Installation

Install with pip from PyPI, then import the codicefiscale module in Python code, or use it from the command line with python -m codicefiscale.

pip install python-codicefiscale

Read the README on GitHub

Points of attention

• The README warns about the command line: if sensitive data is written to a log entry, it could be exposed to someone who gains access to the logs.
• First name suggestions (firstname_options) are partial: for Italian birthplaces about 60% of cases return a single name; for foreign birthplaces the list is empty.

Can an agent use it?

A conventional Python library with a command-line interface. No SKILL.md, AGENTS.md, CLAUDE.md, Cursor rules or MCP server found at the repository root.