Skip to main content

ASCII transliterations of Unicode text

Project description

lossy ASCII transliterations of Unicode text

It often happens that you have text data in Unicode, but you need to represent it in ASCII. For example when integrating with legacy code that doesn’t support Unicode, or for ease of entry of non-Roman names on a US keyboard, or when constructing ASCII machine identifiers from human-readable Unicode strings that should still be somewhat intelligible (a popular example of this is when making an URL slug from an article title).

In most of these examples you could represent Unicode characters as “???” or “\15BA\15A0\1610”, to mention two extreme cases. But that’s nearly useless to someone who actually wants to read what the text says.

What Unidecode provides is a middle road: function unidecode() takes Unicode data and tries to represent it in ASCII characters (i.e., the universally displayable characters between 0x00 and 0x7F), where the compromises taken when mapping between two character sets are chosen to be near what a human with a US keyboard would choose.

The quality of resulting ASCII representation varies. For languages of western origin it should be between perfect and good. On the other hand transliteration (i.e., conveying, in Roman letters, the pronunciation expressed by the text in some other writing system) of languages like Chinese, Japanese or Korean is a very complex issue and this library does not even attempt to address it. It draws the line at context-free character-by-character mapping. So a good rule of thumb is that the further the script you are transliterating is from Latin alphabet, the worse the transliteration will be.

Note that this module generally produces better results than simply stripping accents from characters (which can be done in Python with built-in functions). It is based on hand-tuned character mappings that for example also contain ASCII approximations for symbols and non-Latin alphabets.

This is a C port of Unidecode by Paul Logston <>

Unidecode (by Tomaz Solc) is a Python port of the Text::Unidecode Perl module by Sean M. Burke <> and later

Module content

The module exports a single function that takes an Unicode object (Python 2.x) and returns a string:

>>> from cunidecode import unidecode
>>> unidecode(u'ko\u017eu\u0161\u010dek')
>>> unidecode(u'30 \U0001d5c4\U0001d5c6/\U0001d5c1')
'30 km/h'
>>> unidecode(u"\u5317\u4EB0")
'Bei Jing '


Python 2.x >= 2.6 and a C compiler/linker.

This implementation of unidecode does not “decode” characters outside of the Basic Multilingual Plane. A Python build with “wide” Unicode characters may lead to a segmentation fault if an attempt to decode a character outside the BMP is made.

Surrogate pair encoding of “narrow” builds is not supported.


You install Unidecode, as you would install any Python module, by running these commands:

python install
python test


You can get the latest development version of cUnidecode with:

git clone


Questions, bug reports, useful code bits, and suggestions for Unidecode should be sent to

Questions, bug reports, useful code bits, and suggestions for cUnidecode should be sent to

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cunidecode-0.0.2.tar.gz (95.7 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page