You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
TAHRI Ahmed R 6602dae0c8
📝 Update docs (#219)
3 weeks ago
.github Update python-publish.yml 2 months ago
bin Update 5 months ago
charset_normalizer Fix typos (#213) 1 month ago
data Re-use decoded buffer for single byte character sets (#175) 4 months ago
docs 📝 Update docs (#219) 3 weeks ago
tests Re-use decoded buffer for single byte character sets (#175) 4 months ago
.codecov.yml 🔧 Tweak/adjust the logging verbosity greater-eq to warning level (#147) 10 months ago
.coveragerc ⬆️ Propose v/1.4.0 | Few Improvements | Drop dependencies to reduce the footprint (#41) 1 year ago
.gitignore 🙈 Add .idea and char-dataset/ 1 year ago
.readthedocs.yaml 📝 Docs improvements (#158) 9 months ago Update 2 months ago Create 3 years ago 🔖 Version 2.0.7 (#119) 12 months ago
LICENSE Add LICENSE and data to sdist 3 years ago Finish changelog entries (#143) 10 months ago Update 3 months ago 📝 Documentations adjustments (#46) 1 year ago
dev-requirements.txt ⬆️ Bump black from 22.6.0 to 22.8.0 (#218) 3 weeks ago
setup.cfg Add (#141) 11 months ago 🔥 Remove support for Python 3.5 (#192) 4 months ago

Charset Detection, for Everyone 👋

The Real First Universal Charset Detector
Download Count Total

A library that helps you read text from an unknown charset encoding.
Motivated by chardet, I'm trying to resolve the issue by taking a new approach. All IANA character set names for which the Python core library provides codecs are supported.

>>>>> 👉 Try Me Online Now, Then Adopt Me 👈 <<<<<

This project offers you an alternative to Universal Charset Encoding Detector, also known as Chardet.

Feature Chardet Charset Normalizer cChardet

Reliable without distinguishable standards
Reliable with distinguishable standards
License LGPL-2.1
Native Python
Detect spoken language N/A
UnicodeDecodeError Safety
Whl Size 193.6 kB 39.5 kB ~200 kB
Supported Encoding 33 🎉 93 40

Reading Normalized TextCat Reading Text

** : They are clearly using specific code for a specific encoding even if covering most of used one
Did you got there because of the logs? See

Your support

Fork, test-it, star-it, submit your ideas! We do listen.


This package offer better performance than its counterpart Chardet. Here are some numbers.

Package Accuracy Mean per file (ms) File per sec (est)
chardet 86 % 200 ms 5 file/sec
charset-normalizer 98 % 39 ms 26 file/sec
Package 99th percentile 95th percentile 50th percentile
chardet 1200 ms 287 ms 23 ms
charset-normalizer 400 ms 200 ms 15 ms

Chardet's performance on larger file (1MB+) are very poor. Expect huge difference on large payload.

Stats are generated using 400+ files using default parameters. More details on used files, see GHA workflows. And yes, these results might change at any time. The dataset can be updated to include more files. The actual delays heavily depends on your CPU capabilities. The factors should remain the same. Keep in mind that the stats are generous and that Chardet accuracy vs our is measured using Chardet initial capability (eg. Supported Encoding) Challenge-them if you want.

cchardet is a non-native (cpp binding) and unmaintained faster alternative with a better accuracy than chardet but lower than this package. If speed is the most important factor, you should try it.


Using PyPi for latest stable

pip install charset-normalizer -U

If you want a more up-to-date unicodedata than the one available in your Python setup.

pip install charset-normalizer[unicode_backport] -U

🚀 Basic Usage


This package comes with a CLI.

usage: normalizer [-h] [-v] [-a] [-n] [-m] [-r] [-f] [-t THRESHOLD]
                  file [file ...]

The Real First Universal Charset Detector. Discover originating encoding used
on text file. Normalize text to unicode.

positional arguments:
  files                 File(s) to be analysed

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         Display complementary information about file if any.
                        Stdout will contain logs about the detection process.
  -a, --with-alternative
                        Output complementary possibilities if any. Top-level
                        JSON WILL be a list.
  -n, --normalize       Permit to normalize input file. If not set, program
                        does not write anything.
  -m, --minimal         Only output the charset detected to STDOUT. Disabling
                        JSON output.
  -r, --replace         Replace file when trying to normalize it instead of
                        creating a new one.
  -f, --force           Replace file without asking if you are sure, use this
                        flag with caution.
  -t THRESHOLD, --threshold THRESHOLD
                        Define a custom maximum amount of chaos allowed in
                        decoded content. 0. <= chaos <= 1.
  --version             Show version information and exit.
normalizer ./data/

🎉 Since version 1.4.0 the CLI produce easily usable stdout result in JSON format.

    "path": "/home/default/projects/charset_normalizer/data/",
    "encoding": "cp1252",
    "encoding_aliases": [
    "alternative_encodings": [
    "language": "French",
    "alphabets": [
        "Basic Latin",
        "Latin-1 Supplement"
    "has_sig_or_bom": false,
    "chaos": 0.149,
    "coherence": 97.152,
    "unicode_path": null,
    "is_preferred": true


Just print out normalized text

from charset_normalizer import from_path

results = from_path('./')


Normalize any text file

from charset_normalizer import normalize
    normalize('./') # should write to disk my_subtitle-***.srt
except IOError as e:
    print('Sadly, we are unable to perform charset normalization.', str(e))

Upgrade your code without effort

from charset_normalizer import detect

The above code will behave the same as chardet. We ensure that we offer the best (reasonable) BC result possible.

See the docs for advanced usage :

😇 Why

When I started using Chardet, I noticed that it was not suited to my expectations, and I wanted to propose a reliable alternative using a completely different method. Also! I never back down on a good challenge!

I don't care about the originating charset encoding, because two different tables can produce two identical rendered string. What I want is to get readable text, the best I can.

In a way, I'm brute forcing text decoding. How cool is that ? 😎

Don't confuse package ftfy with charset-normalizer or chardet. ftfy goal is to repair unicode string whereas charset-normalizer to convert raw file in unknown encoding to unicode.

🍰 How

  • Discard all charset encoding table that could not fit the binary content.
  • Measure chaos, or the mess once opened (by chunks) with a corresponding charset encoding.
  • Extract matches with the lowest mess detected.
  • Additionally, we measure coherence / probe for a language.

Wait a minute, what is chaos/mess and coherence according to YOU ?

Chaos : I opened hundred of text files, written by humans, with the wrong encoding table. I observed, then I established some ground rules about what is obvious when it seems like a mess. I know that my interpretation of what is chaotic is very subjective, feel free to contribute in order to improve or rewrite it.

Coherence : For each language there is on earth, we have computed ranked letter appearance occurrences (the best we can). So I thought that intel is worth something here. So I use those records against decoded text to check if I can detect intelligent design.

Known limitations

  • Language detection is unreliable when text contains two or more languages sharing identical letters. (eg. HTML (english tags) + Turkish content (Sharing Latin characters))
  • Every charset detector heavily depends on sufficient content. In common cases, do not bother run detection on very tiny content.

👤 Contributing

Contributions, issues and feature requests are very much welcome.
Feel free to check issues page if you want to contribute.

📝 License

Copyright © 2019 Ahmed TAHRI @Ousret.
This project is MIT licensed.

Characters frequencies used in this project © 2012 Denny Vrandečić