Skip to main content

Name Parser

Build Status PyPI PyPI version Documentation License Downloads Codecov

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 3.1 reads lists of names, not just one name at a time:

  • Parser.suggest() reads a list from one source and returns a parser configured for how it is written: its name order, its patronymics, and family names written as letters or in capitals.

  • Parser.matching() groups and compares names from several sources.

Getting started takes you through both, and the release log has the details. 3.1 also reads Thai titles, a salutation written joined to the given name included (นายสมชาย ใจดี).

Upgrading from 1.x or 2.x? 3.0 removed HumanName and the rest of the 1.x compatibility layer: Coming from 1.x or 2.x below says where to start.

Installation

pip install nameparser

Requires Python 3.11+.

Getting started

Parse one name into its fields:

>>> from nameparser import parse
>>> name = parse("Dr. Juan Carlos García de la Vega III (Juanca)")
>>> name
<ParsedName: [
    title: 'Dr.'
    given: 'Juan'
    middle: 'Carlos García'
    family: 'de la Vega'
    suffix: 'III'
    nickname: 'Juanca'
]>
>>> name.family_base, name.family_particles
('Vega', 'de la')

Have a list of names from one source? A single name often cannot show which word is the family name (in Taylor Morgan either word could be), but a list written one way can. suggest() reads the list and returns a parser that reads it, with the evidence for each setting it considered:

>>> from nameparser import Parser
>>> listing = ["Taylor Morgan", "Kim Minjun", "Wang Xiaoming",
...            "Nguyen Anh", "Garcia Emily"]
>>> suggestion = Parser().suggest(listing)
>>> suggestion.patch
PolicyPatch(name_order=FAMILY_FIRST)
>>> suggestion.parser.parse("Taylor Morgan").given
'Morgan'

Taylor Morgan carries no evidence of its own; it is read family first because the rest of the list is.

Joining records from several sources? matching() gives each name keys to group records by, and checks a pair field by field:

>>> matcher = Parser().matching()
>>> sorted(matcher.keys("Jane A. de la Vega"))
['delavega;j', 'vega;j']
>>> pair = matcher.check("John A. Smith", "J. Smith")
>>> pair.consistent, pair["given"].outcome.value
(True, 'initial')
>>> matcher.check("Jane Smith", "John Smith").consistent
False

More shapes the parser reads

Titles, suffixes and commas. Runs of titles, listing forms and credentials are read without configuration; a guess is reported, and a word the vocabulary read says which languages’ vocabulary it came from:

>>> parse("The Rt Hon Sir John Smith KCB MP").title    # a run of titles
'The Rt Hon Sir'
>>> parse("Dean Smith").given                   # alone, Dean is a given name
'Dean'
>>> parse("Associate Dean Jane Smith").title    # in a title phrase, a title
'Associate Dean'
>>> listed = parse("Smith, John V., Jr., MD, PhD")    # listing form
>>> listed.middle, listed.generation, listed.credentials
('V.', 'Jr.', 'MD, PhD')
>>> parse("Jack MA").suffix                    # capitals mark a credential
'MA'
>>> parse("Jack Ma").family                    # and a surname
'Ma'
>>> dutch = parse("Berg, Jan van der")          # Dutch index form, particles last
>>> dutch.given, dutch.family
('Jan', 'van der Berg')
>>> parse("Van Johnson").ambiguities           # a guess is reported
(Ambiguity('particle-or-given': 'Van'),)
>>> van = parse("Ludwig van Beethoven").tokens[1]
>>> van.reading.languages                    # the vocabulary that read "van"
('nl',)

Other scripts. The default vocabulary reads titles, honorifics and particles in several scripts besides Latin. Chinese, Japanese and Korean names written in their own scripts are read family-first (save a name in katakana alone, often a transcribed foreign name), unspaced Korean names are split against the census surname list, and CJK honorifics are recognized (see East Asian names). Thai writes a salutation joined to the given name with no space, and the parser splits it off, with no configuration (see Thai names).

>>> parse("김민준").family                     # Korean: unspaced, split on the census list
'김'
>>> parse("高橋 みなみ").family                 # Japanese: kanji with kana, family first
'高橋'
>>> parse("김민준씨").honorifics               # an honorific written against the name
'씨'
>>> thai = parse("นายสมชาย ใจดี")              # Thai: the salutation is written joined to
>>> thai.title, thai.given, thai.family       # the given name, and is split off it
('นาย', 'สมชาย', 'ใจดี')
>>> parse("г-н Иван Петров").title             # Cyrillic title
'г-н'
>>> arabic = parse("محمد بن سلمان")            # Arabic: بن chains onto the family name
>>> arabic.family, arabic.patronymic          # and marks it a patronymic
('بن سلمان', 'بن سلمان')
>>> parse("طارق عبد العزيز").family           # عبد + a name of God is one name
'عبد العزيز'
>>> parse("نوال عبد هاشم").family             # هاشم is not one, so it stands alone
'هاشم'

Language packs. The parser never guesses a name’s language, so the conventions of one language are opt-in: a pack reads them when you know the language your data is in, such as two family names in Spanish or the patronymic in Russian. See Locale packs and Notes by language.

>>> 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
'毛'
>>> parse("Сидоров Иван Петрович").given       # read given-first by default
'Сидоров'
>>> russian = parser_for(locales.RU)           # the Russian pack reads the patronymic
>>> ivan = russian.parse("Сидоров Иван Петрович")
>>> ivan.given, ivan.patronymic, ivan.family
('Иван', 'Петрович', 'Сидоров')
>>> locales.available()                        # every pack that ships
('ar', 'bn', 'cs', 'es', 'es_ar', 'ga', 'gd', 'he', 'hi', 'hr', 'ja', 'mn', 'ne', 'pt', 'pt_br', 'ru', 'sk', 'sl', 'tr_az', 'vi', 'zh')

When a reading is wrong for your data

Each reading comes from a word’s readings in the vocabulary or from a Policy setting, and you can change both. Ask the vocabulary what a word may be read as, then add or remove readings and hand the new Lexicon to a Parser:

>>> from nameparser import Lexicon, Policy
>>> [r.kind for r in Lexicon.default().readings_of("dean")]
['office', 'given', 'family']
>>> deans = Lexicon.default().remove("dean", kind="given")    # Dean is always a title
>>> Parser(lexicon=deans).parse("Dean Smith").title
'Dean'
>>> leed = Lexicon.default().add("leed", "ap", kind="credential")
>>> Parser(lexicon=leed).parse("John Smith LEED AP").suffix
'LEED AP'

A Policy says how positions are read, such as which name comes first:

>>> from nameparser import FAMILY_FIRST
>>> hungarian = Parser(policy=Policy(name_order=FAMILY_FIRST))
>>> nagy = hungarian.parse("Nagy Ádám")
>>> nagy.given, nagy.family
('Ádám', 'Nagy')

A Lexicon and a Policy are frozen, so each change returns a new object and nothing is shared between parsers.

If a name still reads wrong, please open an issue with the name and the reading you expected.

Learn more

Coming from 1.x or 2.x

3.0 has no HumanName: parse(text) reads the same seven fields, named given and family where HumanName had first and last, and a Lexicon and Policy handed to a Parser replace Constants. To find what your code has to change:

  1. Upgrade to 2.8.2, which warns of most of what 3.0 removes.

  2. Run your tests under python -W error::DeprecationWarning. The run stops at each use 3.0 removes, except the ones 2.8.2 does not warn on.

  3. Search your code by hand for those: a read of the shared CONSTANTS, a read of a Lexicon set field, and the imports Finding the sites lists.

A pickled HumanName or Constants does not load in 3.0; store parse(text).as_dict() or the original string instead. Migrating to 3.0 maps HumanName’s attributes and the Constants settings onto the 3.0 API.

How well it reads names

These figures give a general idea of what to expect and of how much a setting can change it. Each compares the parser’s fields with the boxes a name was filed in on one large public dataset, after folding case, periods, commas and spacing. That is agreement with someone else’s convention and not ground truth, so they will differ for every dataset and yours will probably match none of them.

  • US patent inventors, at most 20,000 from each country, filed in a given-name and a family-name box: both agree for about 95% of names, and for about 98% outside Spanish- and Portuguese-speaking countries.

  • UK company filings, typed into title, forename, middle-name and surname boxes: all four agree for about 97%.

  • Czech election candidates, with degrees before and after the name: all four boxes agree for about 97%.

  • Choosing the language closes most of the gap. Most of what the default misses is a convention rather than a misreading: it reads one family name, so for researchers in Spain it agrees with the two boxes of their ORCID record for about half of the names, and parser_for(locales.ES) for about 97%. The Spanish pack costs where people file a single surname: Argentine patent inventors agree for about 94% by default, 86% under ES and 93% under ES_AR.

Speed and testing

  • Pure Python, with no runtime dependencies. Only the optional ja extra adds any: namedivider-python and what it brings (numpy, pandas, scipy and lightgbm among them), for dividing unspaced Japanese kanji names.

  • Build one Parser and reuse it. The first parser for a choice of languages in a process costs tens of milliseconds, another choice after it under ten, and building the same choice again about one millisecond, some ten parses; a parse costs roughly a tenth of a millisecond on a recent laptop.

  • A parser can be shared. Its Lexicon and Policy are frozen and a parse never writes to them, so one parser can be shared across threads without locking, and it pickles for multiprocessing. A segmenter you supply has to be thread-safe and picklable too, and the ja extra’s segmenter does not pickle.

  • Every interactive example runs. Each one with a >>> prompt, in this README and in the documentation, is a doctest run in CI, beside a suite of tens of thousands of tests.

The measurements behind this section and the one above, with their dates, counts and commands, are in the project’s record of README figures.

License

LGPL licensed. See LICENSE for details.

The package’s licence expression is LGPL-2.1-or-later. The word lists it ships are the project’s own measurements over public data, and the sources whose licences ask for credit are credited:

  • locales.ES and locales.ES_AR’s given names, measured on Spain’s Instituto Nacional de Estadística census tables (Creative Commons Attribution 4.0), credited in nameparser/locales/_es_given_names.py and _es_ar_given_names.py;

  • part of locales.ZH’s surnames, selected from Taiwan’s Ministry of the Interior surname ranking (Open Government Data License, version 1), credited in nameparser/locales/zh.py.

Metadata

Release files for nameparser 3.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nameparser 3.1.0
File Size Uploaded Provenance Actions
nameparser-3.1.0.tar.gz 2.0 MB With provenance Details for nameparser-3.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for nameparser 3.1.0
File Interpreter ABI Platform Actions
nameparser-3.1.0-py3-none-any.whl Python 3 none any Details for nameparser-3.1.0-py3-none-any.whl

Total release size: 2.8 MB

Release files / nameparser-3.1.0.tar.gz

Download URL nameparser-3.1.0.tar.gz
Size 2.0 MB
Tags Source
SHA-256 checksum
How to use checksums
68eca50ea8c987a3c4f50ffd15be88ce13fbea6245bc333cca8d559dc41dbace
BLAKE2b-256 checksum
How to use checksums
70690fd7c74074fee7650c2799b87944b19cb0ae9fff1e3b8a147fbf1fd0c2c0
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 Nov 17, 2026.

Transparency log

Release files / nameparser-3.1.0-py3-none-any.whl

Download URL nameparser-3.1.0-py3-none-any.whl
Size 794.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
229c547a4f372ce441b01e2e7d812ccfc4f9d7e78064580666b59e0a74ae8bf4
BLAKE2b-256 checksum
How to use checksums
09b870197be237531f2226d3904d7358a4631fccf9cfacadf73798f73a192f56
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 Nov 17, 2026.

Transparency log

Security for nameparser 3.1.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

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for nameparser-3.1.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 Nov 17, 2026.

Transparency log

A 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.

Release history Release notifications | RSS feed

This release

3.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page