Install & Compatibility
Where this runs
tested against v5.0.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.110s · 18.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.094s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
generate_slug
✓ from coolname import generate_slug
generate
✓ from coolname import generate
RandomGenerator
✓ from coolname import RandomGenerator
Used for advanced customization with custom word lists and rules.
This quickstart demonstrates basic usage of `generate_slug` for creating slugs (with default and specified lengths), `generate` for creating word lists, and an example of advanced customization using `RandomGenerator`.
from coolname import generate_slug, generate, RandomGenerator
# Generate a random slug (default length, often 4 words)
print(f"Random slug: {generate_slug()}")
# Generate a slug with a specific number of words
print(f"2-word slug: {generate_slug(2)}")
print(f"3-word slug: {generate_slug(3)}")
# Generate a name as a list of words
name_words = generate()
print(f"Random name (list): {name_words}")
print(f"Joined name: {' '.join(name_words)}")
# Example of custom generator with custom word lists
custom_generator = RandomGenerator({
'all': {
'type': 'cartesian',
'lists': ['adjectives', 'animals']
},
'adjectives': {
'type': 'words',
'words': ['quick', 'sleepy', 'bright']
},
'animals': {
'type': 'words',
'words': ['fox', 'panda', 'owl']
}
})
print(f"Custom generated slug: {custom_generator.generate_slug()}")
Debug
Known issues
breakingThe `coolname` library requires Python 3.10 or newer. Installing on older Python versions will fail.fixUpgrade your Python environment to 3.10 or later.
affects: <4.1.0 (requires >=3.10)
gotchaCalling `generate_slug()` without arguments returns a name of random length, with a higher probability for 4-word names. If you require a consistent number of words, always specify the length (e.g., `generate_slug(2)`). Prepositions and articles ('of', 'from', 'the') are not counted towards the specified word length.fixExplicitly pass the desired word count to `generate_slug(count)` for predictable length.
affects: All versions
gotchaCustomizing word lists or generation rules requires using the `RandomGenerator` class and defining a configuration dictionary. This is more involved than using the simpler `generate()` or `generate_slug()` functions.fixRefer to the GitHub README for examples on configuring `RandomGenerator` with custom dictionaries and rules.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'coolname'
The 'coolname' package is not installed in the Python environment you are currently using or is not accessible on the Python path.
fixInstall the library using pip: `pip install coolname`
ImportError: cannot import name 'non_existent_function' from 'coolname'
You are trying to import a function or class that either does not exist within the 'coolname' package or is misspelled, or you are trying to import something that is not directly exposed at the top level of the package.
fixEnsure the function or class name is spelled correctly and that it is indeed part of the 'coolname' library's public API. Common functions are `generate` and `generate_slug`. For example: `from coolname import generate_slug` or `from coolname import generate`.
if name[0] == 'R' or 'r': # Incorrect boolean logic always returns true
This is a common Python beginner mistake where the boolean `or` operator is misunderstood. The string literal `'r'` is always considered 'truthy' in Python, making the entire condition `True` regardless of `name[0] == 'R'`.
fixEach condition in an `or` statement must be complete and self-contained. The correct way to write this is: `if name[0] == 'R' or name[0] == 'r':` or more Pythonically: `if name[0] in ('R', 'r'):` Upgrade
Version history
5.0.0latest on PyPI · released Apr 23, 2026
Audit
Dependencies
PythonrequiredRequires Python 3.10 or higher.