Name Parser
nameparser parses human names into seven fields — title, given, middle, family, suffix, nickname, maiden. Results are immutable, configuration is composable, and locale packs are opt-in.
📣 nameparser 2.8 is out, the last 2.x feature release.
⚠️ HumanName is deprecated, and 3.0 removes it. From 2.8 the 1.x compatibility layer — HumanName, Constants and the shared CONSTANTS — emits a DeprecationWarning where your code constructs it, loads it from a pickle, or changes the shared CONSTANTS. It keeps working through 2.x; parse() is the replacement, and Coming from 1.x below says where to start. After 2.8 the 2.x line takes fixes only, and new work goes into 3.0.
2.8 also carries on 2.7’s reading of titles that are also given names: a title only inside a title phrase, so Queen Latifah keeps the given name Queen while Her Majesty Queen Elizabeth reads the title. The release log has the details. Please open an issue for anything that parses wrong.
Chinese, Japanese and Korean names written in their own scripts are read family-first, unspaced Korean names are split against the census surname list, and CJK honorifics are recognized. See East Asian names.
Installation
pip install nameparser
Requires Python 3.11+.
Quick Start Example
>>> from nameparser import parse
>>> name = parse("Dr. Juan Q. Xavier de la Vega III (Doc Vega)")
>>> name
<ParsedName: [
title: 'Dr.'
given: 'Juan'
middle: 'Q. Xavier'
family: 'de la Vega'
suffix: 'III'
nickname: 'Doc Vega'
]>
>>> name.family_base, name.family_particles
('Vega', 'de la')
>>> name.given_names, name.surnames
('Juan Q. Xavier', 'Q. Xavier de la Vega')
>>> name.render("{family}, {given}")
'de la Vega, Juan'
>>> parse("Jack MA").suffix # capitals mark a credential
'MA'
>>> parse("Jack Ma").family # and a surname
'Ma'
>>> parse("Jane Smith, PhD MA").suffix
'PhD MA'
>>> parse("김민준").family # Korean: unspaced, split on the census list
'김'
>>> parse("高橋 みなみ").family # Japanese: kanji with kana, family first
'高橋'
>>> parse("김민준씨").suffix # an honorific written against the name
'씨'
>>> parse("г-н Иван Петров").title # Cyrillic title
'г-н'
>>> parse("محمد بن سلمان").family # Arabic: بن chains onto the family name
'بن سلمان'
>>> from nameparser import locales, parser_for
>>> chinese = parser_for(locales.ZH) # Han text does not say which language
>>> chinese.parse("毛泽东").family # so splitting it is opt-in
'毛'
>>> russian = parser_for(locales.RU)
>>> russian.parse("Сидоров Иван Петрович").family
'Сидоров'
>>> locales.available()
('ja', 'ru', 'tr_az', 'zh')Learn more
Using the parser — the full tour: input shapes, aggregates, rendering, comparison, ambiguities, tokens
Customizing the parser — vocabulary, behavior, and presentation
Locale packs — opt-in bundles for East Slavic patronymics, Turkic markers, and more
There’s also a CLI: python -m nameparser --json "Doe, John"
Coming from 1.x
HumanName and CONSTANTS keep working through 2.x — same imports, same attributes, same mutation API — and warn from 2.8 on, since 3.0 removes them. Run your tests under python -W error::DeprecationWarning to find the sites; a read of CONSTANTS does not warn. What 2.0 removes is the batch of deprecations 1.3 and 1.4 announced, so if your test suite runs clean on 1.4 under python -W error::DeprecationWarning, you are nearly done. Two things that check will not catch: four removals 1.4 never warned about (three raise on contact, the fourth only warns), and one that changes results silently — name == "John Smith" is now False. Later 2.x releases add a few breaks of their own. Migrating from HumanName covers all of them, and translates a v1 customization into the new API whenever that’s convenient for you.
See the release log for the full list of changes in the 2.0 series.
License
LGPL licensed. See LICENSE for details.
1 maintainer
Metadata
1 maintainer
Release files for nameparser 2.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| nameparser-2.8.0.tar.gz | 1.4 MB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| nameparser-2.8.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.8 MB
Release files / nameparser-2.8.0.tar.gz
| Download URL | nameparser-2.8.0.tar.gz |
|---|---|
| Size | 1.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fbb6b97d2c000c21a3dccce4e761dd2249c1c77bb75fd6536642c87a93c1ca38
|
|
BLAKE2b-256 checksum How to use checksums |
214ea501fe9da7065c9f5fb970891d46765b723c7b1175de7db17337a633eaf3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Oct 28, 2026.
Transparency logRelease files / nameparser-2.8.0-py3-none-any.whl
| Download URL | nameparser-2.8.0-py3-none-any.whl |
|---|---|
| Size | 482.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1a99a140a01e958849428cd5ac8ec23701d20324fe61f8372b14bfdee5d4823f
|
|
BLAKE2b-256 checksum How to use checksums |
f98f8d37572ddf9f05f1b473e456cd12d93b3a0426516d996070afcec8a095de
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Oct 28, 2026.
Transparency logSecurity for nameparser 2.8.0
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.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for nameparser-2.8.0.tar.gz
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 Oct 28, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
