python-codicefiscale
python-codicefiscale is a library for encode/decode Italian fiscal code - codifica/decodifica del Codice Fiscale.
Features
NEWAuto-updated data (once a week) directly from ANPR data-source.NEWCommand Line Interface available.- Transliteration for name/surname
- Multiple birthdate formats (date/string) (you can see all the supported string formats here)
- Automatic birthplace city/foreign-country code detection from name
- Omocodia support
Installation
pip install python-codicefiscale
Usage
Python
Import
from codicefiscale import codicefiscale
Encode
codicefiscale.encode(
lastname="Caccamo",
firstname="Fabio",
gender="M",
birthdate="03/04/1985",
birthplace="Torino",
)
# "CCCFBA85D03L219P"
Decode
codicefiscale.decode("CCCFBA85D03L219P")
# {
# "code": "CCCFBA85D03L219P",
# "gender": "M",
# "birthdate": datetime.datetime(1985, 4, 3, 0, 0),
# "birthplace": {
# "name": "TORINO"
# "province": "TO",
# "code": "L219",
# },
# "firstname_options": [
# "Fabio",
# ],
# "omocodes": [
# "CCCFBA85D03L219P",
# "CCCFBA85D03L21VE",
# "CCCFBA85D03L2MVP",
# "CCCFBA85D03LNMVE",
# "CCCFBA85D0PLNMVA",
# "CCCFBA85DLPLNMVL",
# "CCCFBA8RDLPLNMVX",
# "CCCFBAURDLPLNMVU",
# ],
# "raw": {
# "code": "CCCFBA85D03L219P",
# "lastname": "CCC",
# "firstname": "FBA",
# "birthdate": "85D03",
# "birthdate_year": "85"
# "birthdate_month": "D",
# "birthdate_day": "03",
# "birthplace": "L219",
# "cin": "P",
# },
# }
[!TIP] Name suggestions: The
firstname_optionsfield contains a list of possible first names matching the encoded firstname code. For Italian birthplaces, in approximately 60% of cases, it returns a single name, providing near-certain identification. In other cases, it returns a list of possible names. For foreign birthplaces, the list is empty.
Check
codicefiscale.is_valid("CCCFBA85D03L219P")
# True
codicefiscale.is_omocode("CCCFBA85D03L219P")
# False
Command Line
[!CAUTION] If sensitive data is written to a log entry it could be exposed to an attacker who gains access to the logs.
This library can be used also as a CLI tool, for more info run:
python -m codicefiscale --help
Encode (CLI)
python -m codicefiscale encode --firstname Fabio --lastname Caccamo --gender M --birthdate 03/04/1985 --birthplace Torino
Decode (CLI)
python -m codicefiscale decode CCCFBA85D03L219P
Testing
# clone repository
git clone https://github.com/fabiocaccamo/python-codicefiscale.git && cd python-codicefiscale
# create virtualenv and activate it
python -m venv venv && . venv/bin/activate
# upgrade pip
python -m pip install --upgrade pip
# install requirements
pip install -r requirements.txt -r requirements-test.txt
# install pre-commit to run formatters and linters
pre-commit install --install-hooks
# run tests using tox
tox
# or run tests using pytest
pytest
License
Released under MIT License.
Supporting
- :star: Star this project on GitHub
- :octocat: Follow me on GitHub
- :blue_heart: Follow me on Bluesky
- :moneybag: Sponsor me on Github
See also
-
python-benedict- dict subclass with keylist/keypath support, I/O shortcuts (base64, csv, json, pickle, plist, query-string, toml, xml, yaml) and many utilities. 📘 -
python-fontbro- friendly font operations. 🧢 -
python-fsutil- file-system utilities for lazy devs. 🧟♂️
1 maintainer
Release files for python-codicefiscale 0.12.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| python_codicefiscale-0.12.1.tar.gz | 428.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| python_codicefiscale-0.12.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 866.1 kB
Release files / python_codicefiscale-0.12.1.tar.gz
| Download URL | python_codicefiscale-0.12.1.tar.gz |
|---|---|
| Size | 428.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
80ade613229d9e7ca4983c26c81bd680982862b089e205c3ee157a292f675610
|
|
BLAKE2b-256 checksum How to use checksums |
8939a7ae8d4dac5523867ad613910d02b40e0bd70e7d8ec91c7ad27b1b7ed978
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 8, 2026.
Transparency logRelease files / python_codicefiscale-0.12.1-py3-none-any.whl
| Download URL | python_codicefiscale-0.12.1-py3-none-any.whl |
|---|---|
| Size | 437.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
403f029ce8a184650d969ef0eb604b3457128dff4b057de1ee40a56f0674733d
|
|
BLAKE2b-256 checksum How to use checksums |
3f8a4ed178574008c87a78927915a6eb956e5668af855ca0c795e499b425a746
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 8, 2026.
Transparency log
