Guide · Open source

How to use ddddocr: install and recognize captcha text in Python

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

ddddocr is an MIT-licensed Python library for recognizing text in captcha images. It runs its models locally, so you do not need to call an online service. This guide covers installation, a basic recognition call, character-set limits and the main limits the project itself documents, so you know what to expect.

ddddocrsml2h3/ddddocr · ★ 14.9k · MIT Install options & downloads

Quick start

1Check your environment. Confirm you are on a 64-bit system running Python 3.12 or earlier, since the README sets 3.12 as the maximum supported version.
2Install the package. Run pip install ddddocr to install the PyPI release.
3Create the OCR object. Call ddddocr.DdddOcr() once in your script and keep the object for reuse.
4Read the image as bytes. Open your captcha image file in binary mode and read its contents.
5Run classification. Pass the bytes to classification() and print the returned text.
6Restrict characters if needed. Call set_ranges() with a built-in option or your own character string to limit output.

What are the system requirements for ddddocr?

The README lists Windows 64-bit, Linux 64 and ARM64, and macOS X64 as supported, with CPU and GPU options. The maximum supported Python version is 3.12. Windows 32-bit and Linux 32-bit are not supported.

Some Windows versions need the vc runtime library, and the README links a separate note for M1/M2/M3 Mac users.

Python, with a maximum supported version of 3.12
pip
A 64-bit operating system

Install ddddocr with pip

The recommended method is to install the PyPI package. The README also documents installing from source and an optional API extra, but the PyPI route is the simplest.

Do not import ddddocr from inside the ddddocr project root directory. Name your own project folder something other than ddddocr.

pip install ddddocr

Run your first captcha recognition

Create the DdddOcr object once and reuse it. Re-initializing for every image slows things down, according to the README. Read your image as bytes and pass them to classification(), which returns the recognized text.

The README shows this for Chinese, English and digit captchas that are simple single-line images. Results depend on the captcha.

Create one DdddOcr() instance and reuse it
Pass the image as bytes to classification()
Print the returned string

import ddddocr

# 初始化OCR对象
ocr = ddddocr.DdddOcr()

# 读取图片
with open("验证码图片.jpg", "rb") as f:
    image = f.read()

# 识别图片
result = ocr.classification(image)
print(result)  # 输出识别结果

Limit the characters ddddocr can return

If you know the captcha only uses digits or certain letters, call set_ranges() to restrict the output. The README lists built-in options 0 to 7, where 0 is digits only and 7 is the default set without lowercase, uppercase or digits. You can also pass your own string of characters.

Use probability=True to get per-character probabilities from the built-in models, which can help you pick the best character yourself. The README notes that custom models ignore this flag.

Option 0: digits 0-9
Option 3: lowercase plus uppercase letters
Option 6: lowercase, uppercase and digits
A custom string such as "0123456789+-x/="

ocr.set_ranges("0123456789+-x/=")
result = ocr.classification(image)
print(result)

Choose a model: default or beta

The library ships two OCR models. The default is common_old.onnx. Setting beta=True switches to common.onnx, which the README says works better on some complex captchas. Object detection is enabled with det=True, and sliding-captcha gap detection uses slide_match or slide_comparison.

If neither built-in model fits, the README points to dddd_trainer for training your own model. A custom model needs an onnx file and a charsets json file passed as import_onnx_path and charsets_path.

Default: common_old.onnx
beta=True: common.onnx
det=True: object detection mode
import_onnx_path with charsets_path: custom model mode

ocr = ddddocr.DdddOcr(beta=True)

Known limits and when to pick another tool

The README says accuracy varies. Simple captchas tend to work well, while complex or modern ones may need a custom model. GPU acceleration needs CUDA and a matching onnxruntime-gpu build, or initialization fails.

Use ddddocr only on sites you own or have explicit permission to test. The project targets legitimate recognition use, and automating captcha solving on other people's sites carries legal and ethical risk. The README lists tesseract, PaddleOCR and EasyOCR as comparable projects you can evaluate.

Accuracy depends on the captcha; the README advises training custom models for harder cases
GPU use requires CUDA and onnxruntime-gpu
Compare with tesseract, PaddleOCR or EasyOCR before committing

What people use it for

Automated tests on your own web application that uses a simple image captcha
Offline digit or letter reading in a Python script with a fixed character set
Experimenting with sliding-captcha gap detection on a test site you control
Trying the built-in model before deciding whether to train a custom one with dddd_trainer

Frequently asked questions

Is ddddocr free to use?

ddddocr is released under the MIT licence, as stated in the project information. The README does not list any paid tier for the library itself. Some sponsors are listed in the README, but they are separate services.

What Python version does ddddocr need?

The README states that the maximum supported Python version is 3.12. Use a Python version at or below that when you install the package. Windows 32-bit and Linux 32-bit are not supported at all.

How do I install ddddocr?

Run pip install ddddocr. The README recommends this PyPI route. You can also install from source by cloning the repository and running pip install ., but the PyPI method is the one listed first.

Does ddddocr work offline?

Yes. The project describes itself as an offline local recognition SDK, and the models run locally rather than calling an online service.

Why is my ddddocr result wrong?

The README says accuracy varies by captcha. Try beta=True, restrict characters with set_ranges(), or check the README's preprocessing and custom-model sections. For complex captchas, the project suggests training a custom model.

How does ddddocr compare to tesseract or PaddleOCR?

The README lists tesseract, PaddleOCR and EasyOCR as comparable projects but does not benchmark them against ddddocr. Its stated design goal is minimal dependencies and a simple API, so test each one on your own captcha samples before choosing.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

ddddocr suits Python developers who need to read simple image captchas locally on sites they own or are authorized to test. It is less suitable if you need guaranteed accuracy on modern or complex captchas, or if you run 32-bit systems. For those cases, evaluate tesseract, PaddleOCR or EasyOCR, or train a custom model.

Install options & downloads