Install & Compatibility
Where this runs
tested against v0.18.1 · 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.066s · 24.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.058s · 25MB
22MB installed
● package 22MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Pyphen
✓ from pyphen import Pyphen
The primary class for creating a hyphenator instance.
language_fallback
✓ import pyphen; pyphen.language_fallback(...)
Utility function for language fallback logic, typically accessed via the module.
LANGUAGES
✓ import pyphen; pyphen.LANGUAGES
A dictionary containing available language codes and their dictionary paths, accessed via the module.
Initialize a `Pyphen` object for a desired language. The quickstart demonstrates basic hyphenation using `inserted()`, word wrapping with `wrap()`, and iterating through all possible hyphenation points with `iterate()`. It also shows how to check for available languages using `pyphen.LANGUAGES`. Dictionaries are automatically loaded upon instantiation.
import pyphen
# Instantiate Pyphen for a specific language (e.g., French)
dic = pyphen.Pyphen(lang='fr_FR')
# Check if a language is available
print(f"Is 'fr_FR' available? {'fr_FR' in pyphen.LANGUAGES}")
# Hyphenate a word, inserting hyphens
word = 'fromage'
hyphenated_word = dic.inserted(word)
print(f"'{word}' hyphenated: {hyphenated_word}") # Expected: 'fro-mage'
# Wrap a word to a certain width
long_word = 'autobandventieldopje'
wrapped_word = dic.wrap(long_word, 11)
print(f"'{long_word}' wrapped to 11 chars: {wrapped_word}") # Expected: ('autoband-', 'ventieldopje')
# Iterate over all possible hyphenation points
print(f"Hyphenation iterations for 'Amsterdam':")
for pair in dic.iterate('Amsterdam'):
print(pair)
Debug
Known issues
breakingPyphen regularly drops support for older Python versions. For instance, v0.17.0 dropped Python 3.8, v0.15.0 dropped 3.7, and v0.12.0 dropped 3.6. Ensure your Python environment meets the `requires_python` specification, which is currently `>=3.9`.fixUpgrade your Python environment to at least version 3.9 (or newer, as dictated by the specific Pyphen version you are using) to maintain compatibility. Check `requires_python` on PyPI or the official changelog for specific version requirements.
affects: 0.12.0, 0.15.0, 0.17.0 and newer
gotchaInitializing a `Pyphen` instance, particularly with large dictionaries, can be a time-consuming operation, especially on resource-constrained devices like a Raspberry Pi Zero where it might take tens of seconds. The delay occurs during dictionary parsing and setup.fixInstantiate `Pyphen` once and reuse the object throughout your application rather than creating new instances repeatedly. Consider lazy loading if hyphenation is not immediately required.
affects: All versions
gotchaThe correctness of hyphenation is dependent on the quality and rules of the underlying Hunspell dictionaries. Occasionally, certain words or language nuances might lead to unexpected hyphenation points or errors (e.g., specific issues reported for Polish or German words).fixFor persistent issues with specific words or languages, it may be necessary to consult the upstream LibreOffice dictionaries or contribute fixes there. Pyphen itself uses these dictionaries without modification.
affects: All versions
deprecatedStarting from version 0.15.0, Pyphen transitioned from `pkg_resources` to `importlib.resources` for resource management. While `pkg_resources` might still function in some older setups, it is officially deprecated in Python.fixIf you are directly interacting with Pyphen's internal resource loading mechanisms (which is uncommon for typical usage), update your code to use `importlib.resources` for future compatibility. Standard usage `pyphen.Pyphen(lang='...')` is unaffected.
affects: 0.15.0 and newer
breakingPyphen might fail to find or load dictionaries for certain languages, especially in minimal container environments (e.g., `-slim` Docker images) or if the required dictionary files (e.g., `hyph_fr_FR.dic`) are not present in expected locations. This can lead to `Pyphen(lang='your_lang')` effectively failing or returning `None`.fixEnsure that the necessary hyphenation dictionary files for your desired languages are installed and accessible in your environment. For Docker, this may involve installing `locales` or specific dictionary packages, or manually copying dictionary files into the image. Refer to Pyphen's documentation for details on dictionary installation and path configuration.
affects: All versions
breakingIn certain environments, particularly minimal ones like Alpine Linux-based Docker images, Pyphen might fail to locate or load specific language dictionaries. This can manifest as `Pyphen(lang='...')` not finding the requested dictionary, or `is_registered('...')` returning `False` for a language that should be available. This issue is often related to the interaction between Python's resource loading mechanisms (`importlib.resources`) and the specific filesystem layout or missing low-level system dependencies in such minimal environments.fixVerify that the `pyphen` package and its data files are correctly installed and accessible within the environment. For Alpine-based images, ensure that the Python environment has all necessary runtime dependencies that might impact resource discovery. It might be necessary to manually inspect the `pyphen/dictionaries` directory within your site-packages to confirm dictionary file presence and accessibility, or consider using a less minimal base image if resource loading issues persist.
affects: All versions (more prominent in 0.15.0+ due to `importlib.resources` transition, and environment-dependent)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pyphen'
The 'pyphen' package has not been installed in the current Python environment or is not accessible.
fixInstall the package using pip: `pip install pyphen`
KeyError: "Dictionary 'xx_XX' not found."
The specified language code for hyphenation does not correspond to a dictionary bundled with pyphen, or the custom dictionary path is incorrect.
fixUse a valid language code (e.g., 'en_US', 'de_DE'). You can list available dictionaries with `pyphen.LANGUAGES`.
AttributeError: module 'pyphen' has no attribute 'hyphenate'
The `hyphenate` method is being called directly on the `pyphen` module itself, instead of on an instantiated `Pyphen` object.
fixFirst, create an instance of the `Pyphen` class with a specific language, then call `hyphenate` on that instance: `ph = pyphen.Pyphen(lang='en_US'); ph.hyphenate('word')` Upgrade
Version history
0.18.1latest on PyPI · released Aug 14, 2026
Audit
Dependencies
No dependency data recorded yet.