unidecode

library1.4.0pypypi✓ verified 26d ago

Unidecode is a Python library that provides ASCII transliterations of Unicode text. It converts non-ASCII Unicode characters into their closest ASCII approximations, which is useful for tasks like generating URL slugs or integrating with legacy systems. The current version is 1.4.0, with releases occurring as improvements to transliteration tables are made, rather than on a fixed schedule.

serialization data

pip install unidecode

package ↗homepage ↗

INSTALL

IMPORT

SIG · UNIDECODE

unidecode

serializationpythonv1.4.0

Install

1.7s avg

Import

11ms

Disk

18MB

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.012s · 19.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.006s · 20MB

18MB installed

● package 18MB

Code

Verified usage

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

unidecode

✓ from unidecode import unidecode

Demonstrates how to import and use the `unidecode` function for basic transliteration and a common use case like generating URL slugs.

from unidecode import unidecode # Basic transliteration text_unicode = 'Łódź, 北京, Español' text_ascii = unidecode(text_unicode) print(f"Original: {text_unicode}") print(f"Transliterated: {text_ascii}") # Example for URL slug generation (common use case) article_title = 'The "Café" where you can find "Piñatas"!' slug = unidecode(article_title).replace(' ', '-').lower() print(f"\nURL Slug: {slug}")

Debug

Known issues

breakingThe output of `unidecode()` is not guaranteed to be stable across different versions of the library. Improvements to transliteration tables can cause the ASCII approximation for certain Unicode characters to change in new releases.

fix

If using `unidecode()` to generate persistent identifiers like URL slugs, either lock your `unidecode` dependency to a specific version or generate the slug once and store it in your database, rather than re-generating on the fly.

affects: All versions, especially when upgrading between minor or major releases.

gotchaUnidecode performs a context-free, character-by-character mapping and is not language-specific. This means transliterations may not align with linguistic rules or cultural expectations for all languages (e.g., German umlauts are 'a', 'o', 'u' instead of 'ae', 'oe', 'ue'; East Asian languages may have simplified mappings).

fix

For language-specific or more sophisticated transliterations (especially for Japanese, Chinese, Korean), consider using libraries designed for those specific languages or implement pre-processing rules before using `unidecode()`.

affects: All versions.

gotchaUnidecode requires a Python build with 'wide' Unicode characters (UCS-4 build) to correctly handle characters outside the Basic Multilingual Plane (BMP). 'Narrow' Python builds using surrogate pair encoding are not supported, which can lead to incorrect transliterations for mathematical symbols, emojis, etc.

fix

Ensure your Python environment is built with 'wide' Unicode support (typically `sys.maxunicode > 0xffff`). This is usually the default for Python 3.7+ builds but can vary by system configuration.

affects: All versions, for Python environments with 'narrow' Unicode builds.

gotchaThe `unidecode` function expects a Unicode string (Python 3 `str`) as input. Passing byte data (e.g., from reading a file in binary mode) will result in a `TypeError` or incorrect output.

fix

Always ensure your input is a properly decoded Unicode string before passing it to `unidecode()`. If reading from a file, open it in text mode with the correct encoding (e.g., `open('file.txt', 'r', encoding='utf-8')`).

affects: All Python 3.x versions.

gotchaThe output of `unidecode` is a 'lossy' approximation. Since some characters map to `''` (empty string) or generic characters (like `?`), and due to its non-linguistic approach, the transliterated output should not be directly exposed to users without careful consideration, as it may be perceived as offensive or simply incorrect.

fix

Use `unidecode` primarily for internal system identifiers, search indexing, or compatibility with ASCII-only systems, not as a user-facing display mechanism. Always consider the context and potential user perception of the transliterated text.

affects: All versions.

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'unidecode'

The unidecode library has not been installed in the current Python environment.

fix

pip install unidecode

TypeError: 'module' object is not callable

The unidecode module was imported directly, but the user attempted to call the module object as a function instead of calling the 'unidecode' function defined within it.

fix

import unidecode
result = unidecode.unidecode("Héllø Wörld")
# Alternatively, import the function directly:
# from unidecode import unidecode
# result = unidecode("Héllø Wörld")

ImportError: cannot import name 'Unidecode' from 'unidecode'

The 'unidecode' function was imported with incorrect capitalization; the function name is lowercase 'unidecode'.

fix

from unidecode import unidecode
text = unidecode("München")

TypeError: expected string or bytes-like object, got int

The unidecode function received an argument that is an integer (or another non-string/bytes type), but it exclusively expects a string or bytes-like object.

fix

value = 123
text = unidecode(str(value)) # Ensure the input is a string

Upgrade

Version history

1.4.0latest on PyPI · released Apr 24, 2025

Audit

Dependencies

pythonrequiredRequires Python 3.7 or later for execution.

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

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

homepagehttps://pypi.org/project/Unidecode/ ↗