nameparser

library2.1.0pypypi✓ verified 24d ago

Nameparser is a simple Python module designed for parsing human names into their distinct components, such as title, first, middle, last, suffix, and nickname. It supports a variety of common name formats for Latin-based languages and is currently at version 1.1.3, receiving updates for bug fixes and feature enhancements.

serialization

pip install nameparser

github ↗package ↗

INSTALL

IMPORT

SIG · NAMEPARSER

nameparser

serializationpythonv2.1.0

Install

1.6s avg

Import

189ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.4.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.190s · 18.4MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.188s · 19MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

HumanName

✓ from nameparser import HumanName

Parses a full name string into a `HumanName` object, allowing access to its individual components as attributes like `title`, `first`, `middle`, `last`, `suffix`, and `nickname`.

from nameparser import HumanName name = HumanName("Dr. Juan Q. Xavier de la Vega III (Doc Vega)") print(f"Title: {name.title}") print(f"First: {name.first}") print(f"Middle: {name.middle}") print(f"Last: {name.last}") print(f"Suffix: {name.suffix}") print(f"Nickname: {name.nickname}") print(f"Full Name (formatted): {name}")

Debug

Known issues

breakingThe `full_name` attribute's behavior changed. Before v1.0.4, it returned the original input string. Since v1.0.4, it returns a formatted string output based on the parsed components.

fix

If you relied on `full_name` returning the exact original string, store the original string separately or adjust your code to expect the formatted output.

affects: >=1.0.4

breakingVersion 1.0.0 introduced significant refactoring of prefix handling and support for prefixes on first names, which may alter parsing results for certain names compared to older versions.

fix

Thoroughly test parsing outcomes for a representative set of names if upgrading from pre-1.0.0 versions to ensure consistent results.

affects: >=1.0.0

gotchaIf you customize the parser's constants (e.g., adding new titles, prefixes, suffixes) after a `HumanName` instance has been created or its `full_name` attribute set, you must explicitly call `name.parse_full_name()` to re-parse the name and apply the new configurations.

fix

Call `name_instance.parse_full_name()` after modifying constants that affect parsing or ensure constants are configured before instantiation/first parsing.

affects: All versions

gotchaBy default, `HumanName` will not adjust the capitalization of names that are already in mixed case. It primarily corrects all upper or all lower case names.

fix

To force capitalization of mixed-case names, use `name.capitalize(force=True)` or set `nameparser.config.CONSTANTS.force_mixed_case_capitalization = True` globally.

affects: All versions

gotchaThe library is primarily designed for English names. While it can be useful for other Latin-based languages, it may not perform optimally for languages with significantly different name structures without custom configuration.

fix

For non-English names, consider customizing `nameparser.config.Constants` with language-specific titles, prefixes, and suffixes, or evaluate alternative libraries if primary use is non-Latin or non-English.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'nameparser'

The 'nameparser' library is not installed in the current Python environment or the environment is not correctly activated.

fix

Install the library using pip: `pip install nameparser`

AttributeError: 'HumanName' object has no attribute 'middle_name'

The user is attempting to access a name component using an incorrect attribute name. The correct attribute for middle names is 'middle'.

fix

Use the correct attribute name, for example: `name.middle` instead of `name.middle_name`.

TypeError: Can only assign strings, lists or None to name attributes. Got <class 'int'>

A `HumanName` attribute (like `first`, `middle`, `last`, etc.) was assigned a value that is not a string, a list of strings, or `None`.

fix

Ensure that values assigned to `HumanName` attributes are always strings, lists of strings, or `None`.

Upgrade

Version history

2.1.0latest on PyPI · released Aug 7, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/derek73/python-nameparser ↗

packagehttps://pypi.org/project/nameparser/ ↗