Nicknames

1.0.1 · active · verified Thu Apr 16

The 'nicknames' library provides a hand-curated dataset of English given names and their associated nicknames or diminutive names. It offers a Python API to query these relationships. The current version is 1.0.1, released on March 5, 2026, and follows a release cadence tied to data updates and feature enhancements. It is actively maintained by the Old Dominion University - Web Science and Digital Libraries Research Group. [4, 5]

Common errors

```
ModuleNotFoundError: No module named 'nicknames.NickNamer'
```
cause Attempting to import `NickNamer` directly from a submodule instead of the top-level package. [4]

fix The `NickNamer` class is directly available from the `nicknames` package. Use `from nicknames import NickNamer`.
```
AttributeError: 'NickNamer' object has no attribute 'load_resource'
```
cause The `load_resource()` function was removed in version 1.0.0. [10]

fix For lower-level access to the CSV data, use `name_triplets()` directly or explore `with_names_csv_path()` and `name_relationships()` if you need custom data loading paths. [4, 10]
```
AssertionError: 'alexander' not in nn.nicknames_of('al')
```
cause Misunderstanding the non-symmetric nature of nickname relationships. 'Alexander' is a canonical name, 'al' is a nickname for 'Alexander', but 'Alexander' is not a nickname for 'al'. [4]

fix Use `nn.canonicals_of('al')` to find canonical forms like 'alexander', or combine results from both `nicknames_of` and `canonicals_of` for a comprehensive check. [4]

Warnings

breaking Version 1.0.0 (released July 14, 2025) introduced a significant breaking change by switching the underlying data format from a 'wide' format to a 'long' format using semantic triplets (name1, relationship, name2). This impacts direct CSV parsing if you were bypassing the Python API. [10]
Fix: Migrate any direct CSV parsing logic to use the `NickNamer` class methods (`nicknames_of`, `canonicals_of`) or the new lower-level `name_triplets`, `with_names_csv_path`, `name_relationships` functions, which correctly interpret the new semantic triplet format. [4, 10]
breaking Python 3.7 support was removed in version 1.0.0. Additionally, legacy Perl, Java, and R bindings and the `load_resource()` Python function were deprecated and removed. [10]
Fix: Ensure your project uses Python 3.8 or higher. If you were using `load_resource()`, switch to `with_names_csv_path()` or `name_relationships()` for lower-level CSV access. [4, 10]
gotcha The relationship between a name and its nickname is not always symmetric. For example, 'al' is a nickname for 'alexander', but 'alexander' is not considered a nickname for 'al'. Direct lookups should account for this. [4]
Fix: When checking for equivalence or relatedness, consider querying both directions (e.g., `nn.nicknames_of("name")` and `nn.canonicals_of("name")`) or combining results from both `nicknames_of` and `canonicals_of` as shown in the quickstart. [4]
gotcha The dataset, due to its original source (genealogy page from the Center for African American Research, Inc.), has a bias towards traditionally African American names. Other name groups may be underrepresented or absent. [5]
Fix: Be aware of this data bias when using the library for applications requiring broader demographic coverage. Contribution to expand the dataset is welcomed by the maintainers. [5]

Install

pip install nicknames Install stable version

Imports

NickNamer
```
from nicknames import NickNamer
```
name_triplets
```
from nicknames import name_triplets
```
Provides direct access to the raw data as a list of NamedTuples.

Quickstart

This quickstart demonstrates how to instantiate the `NickNamer` class to find nicknames for a given name and canonical names for a given nickname. It also shows how to combine these methods to check for interchangeability and how to access the raw `name_triplets` data directly. [4]

from nicknames import NickNamer, name_triplets

# Initialize the NickNamer class
nn = NickNamer()

# Get nicknames for a given name
nicks_for_alexander = nn.nicknames_of("Alexander")
print(f"Nicknames for Alexander: {nicks_for_alexander}")
# Expected: {'al', 'alex'}

# Get canonical names for a given nickname
canonicals_for_al = nn.canonicals_of("al")
print(f"Canonical names for al: {canonicals_for_al}")
# Expected: {'alexander', 'alex'}

# Check if two names are interchangeable (via nicknames or canonical forms)
alexander_is_al_interchangeable = "alexander" in (nn.nicknames_of("al") | nn.canonicals_of("al"))
print(f"Is Alexander interchangeable with al? {alexander_is_al_interchangeable}")

# Access the raw data triplets
first_three_triplets = name_triplets()[:3]
print(f"First three raw name triplets: {first_three_triplets}")

view raw JSON →