ddddocr

library1.6.1pypypi✓ verified 85d ago

DdddOcr is a universal offline CAPTCHA recognition SDK that leverages deep learning models to identify various types of CAPTCHAs, including alphanumeric, Chinese characters, slider puzzles, and special character combinations. It is designed with minimal dependencies for ease of use and offers a simple API. The current version is 1.6.1 and is actively maintained with frequent updates.

ai-ml auth-security

pip install ddddocr

github ↗package ↗

INSTALL

IMPORT

SIG · DDDDOCR

ddddocr

ai-mlpythonv1.6.1

Install

11.6s avg

Import

495ms

Disk

440MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.6.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

musl

py 3.10–3.940 runs

build_error

glibc

py 3.10–3.940 runs

installs and imports cleanly · install 11.6s · import 0.495s · 478MB

440MB installed

● package 440MB

Code

Verified usage

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

DdddOcr

✓ import ddddocr ocr = ddddocr.DdddOcr()

✗ from ddddocr import DdddOcr # (if current directory is 'ddddocr')

Avoid direct `from ddddocr import ...` or having a local directory named `ddddocr` to prevent import conflicts.

This quickstart demonstrates basic text recognition using the DdddOcr class. It initializes the OCR engine once and then processes an image from bytes. Remember to initialize the `DdddOcr` object only once for performance.

import ddddocr import os # Create a dummy image file for demonstration dummy_image_path = 'captcha_example.png' from PIL import Image, ImageDraw, ImageFont # Create a simple image with text img = Image.new('RGB', (120, 40), color = (255, 255, 255)) d = ImageDraw.Draw(img) try: # Try to use a common system font font = ImageFont.truetype('arial.ttf', 24) except IOError: # Fallback if arial.ttf is not found font = ImageFont.load_default() d.text((10,5), "test123", fill=(0,0,0), font=font) img.save(dummy_image_path) # Initialize DdddOcr for OCR recognition # It's recommended to initialize the object once, not in a loop. ocr = ddddocr.DdddOcr() # Read the image bytes with open(dummy_image_path, 'rb') as f: image_bytes = f.read() # Perform OCR classification result = ocr.classification(image_bytes) print(f"OCR Result: {result}") # Clean up the dummy image os.remove(dummy_image_path)

Debug

Known issues

gotchaInitializing the `DdddOcr` object repeatedly (e.g., inside a loop) will significantly slow down performance due to model loading overhead.

fix

Initialize the `ddddocr.DdddOcr()` object only once and reuse the instance for multiple recognition tasks.

affects: All versions

gotchaWhen using `ddddocr` in a multi-threaded environment, each thread must create its own independent `DdddOcr` instance to prevent recognition errors or inconsistent results.

fix

Ensure that `ddddocr.DdddOcr()` is instantiated within each thread that requires OCR capabilities.

affects: All versions

gotchaIf your project directory (or a parent directory) is named `ddddocr`, you might encounter import conflicts, leading to `ModuleNotFoundError` or unexpected behavior.

fix

Rename your project directory to anything other than `ddddocr` to avoid conflicts with the installed package name.

affects: All versions

gotchaWhen initializing `DdddOcr`, if both `ocr=True` and `det=True` are set, the object detection mode (`det`) takes precedence. Similarly, `beta=True` overrides `old=True` if both are specified.

fix

Explicitly set only the desired mode (e.g., `ddddocr.DdddOcr(ocr=True, det=False)` for OCR or `ddddocr.DdddOcr(ocr=False, det=True)` for detection) to avoid unintended behavior.

affects: All versions

gotchaEnabling GPU acceleration (`use_gpu=True`) requires a compatible CUDA setup and `onnxruntime-gpu`. Incorrect CUDA/cuDNN versions or missing ONNX Runtime dynamic link libraries can lead to errors.

fix

Install the correct versions of CUDA and cuDNN matching your `onnxruntime-gpu` requirements. For static linking issues, manually place `onnxruntime` DLLs in the program's running directory or use `Ddddocr::set_onnxruntime_path` if using dynamic linking.

affects: All versions

Errors

Common errors & fixes

Initialization speed is slow when creating DdddOcr objects.

The `DdddOcr` model is loaded during initialization, and repeated instantiation in a loop causes this overhead for each image.

fix

Initialize the `ddddocr.DdddOcr()` object once outside any loops and reuse it for all subsequent recognition calls. Example: `ocr = ddddocr.DdddOcr(); for img in images: result = ocr.classification(img_bytes)`

ModuleNotFoundError: No module named 'ddddocr' (or similar import errors) OR unexpected behavior when importing ddddocr.

Your project directory, or a directory in your `PYTHONPATH`, is likely named `ddddocr`, which conflicts with the installed library package name.

fix

Rename your project directory to something other than `ddddocr`. This ensures that Python correctly imports the installed package.

OCR recognition accuracy is not as expected for specific CAPTCHAs.

The default OCR model might not be optimized for all types of complex or custom CAPTCHAs.

fix

Try using the Beta model by initializing with `ocr = ddddocr.DdddOcr(beta=True)`. For very specific cases, consider using the color filtering feature or importing a custom-trained model.

ddddocr uses too much memory when multiple functionalities are needed.

Initializing multiple `DdddOcr` instances with different functional parameters (e.g., one for OCR, another for detection) simultaneously.

fix

Initialize only the specific `DdddOcr` instance(s) needed for the current task. For example, if you only need OCR, use `ocr = ddddocr.DdddOcr(ocr=True, det=False)` and avoid initializing a separate detection object if not immediately required.

Error: 'cuda may painc (exit code: 0xc000007b)' or missing DLL errors when using GPU acceleration.

This typically indicates an incompatibility between your CUDA/cuDNN installation and `onnxruntime`, or issues with `onnxruntime` dynamic link library (DLL) loading paths.

fix

Verify your CUDA and cuDNN versions are compatible with your `onnxruntime-gpu` installation. Ensure the `onnxruntime` DLLs are accessible to your application (e.g., in the system's PATH, or application's running directory). For specific cases, especially with static linking, you might need to manually place or configure the `onnxruntime` library path.

Upgrade

Version history

1.6.1latest on PyPI · released Mar 11, 2026

Audit

Dependencies

numpyrequiredNumerical operations for image processing and model inference.

onnxruntimerequiredCore runtime for ONNX model inference.

PillowrequiredImage processing library.

opencv-pythonoptionalImage processing on Windows and macOS.

opencv-python-headlessoptionalImage processing on Linux (headless version to avoid GUI dependencies).

fastapioptionalRequired for the optional API server functionality.

uvicornoptionalASGI server for the optional API.

python-multipartoptionalRequired for handling form data in the API.

pydanticoptionalData validation for the API.

Agent activity

104 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/sml2h3/ddddocr ↗

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