{"id":8079,"library":"ddddocr","title":"DDDDOCR","description":"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.","status":"active","version":"1.6.1","language":"en","source_language":"en","source_url":"https://github.com/sml2h3/ddddocr","tags":["OCR","CAPTCHA","image processing","deep learning","offline","verification code"],"install":[{"cmd":"pip install ddddocr","lang":"bash","label":"Standard Installation"},{"cmd":"pip install \"ddddocr[api]\"","lang":"bash","label":"Installation with API Server Dependencies"}],"dependencies":[{"reason":"Numerical operations for image processing and model inference.","package":"numpy"},{"reason":"Core runtime for ONNX model inference.","package":"onnxruntime"},{"reason":"Image processing library.","package":"Pillow"},{"reason":"Image processing on Windows and macOS.","package":"opencv-python","optional":true},{"reason":"Image processing on Linux (headless version to avoid GUI dependencies).","package":"opencv-python-headless","optional":true},{"reason":"Required for the optional API server functionality.","package":"fastapi","optional":true},{"reason":"ASGI server for the optional API.","package":"uvicorn","optional":true},{"reason":"Required for handling form data in the API.","package":"python-multipart","optional":true},{"reason":"Data validation for the API.","package":"pydantic","optional":true}],"imports":[{"note":"Avoid direct `from ddddocr import ...` or having a local directory named `ddddocr` to prevent import conflicts.","wrong":"from ddddocr import DdddOcr # (if current directory is 'ddddocr')","symbol":"DdddOcr","correct":"import ddddocr\nocr = ddddocr.DdddOcr()"}],"quickstart":{"code":"import ddddocr\nimport os\n\n# Create a dummy image file for demonstration\ndummy_image_path = 'captcha_example.png'\nfrom PIL import Image, ImageDraw, ImageFont\n\n# Create a simple image with text\nimg = Image.new('RGB', (120, 40), color = (255, 255, 255))\nd = ImageDraw.Draw(img)\ntry:\n    # Try to use a common system font\n    font = ImageFont.truetype('arial.ttf', 24)\nexcept IOError:\n    # Fallback if arial.ttf is not found\n    font = ImageFont.load_default()\nd.text((10,5), \"test123\", fill=(0,0,0), font=font)\nimg.save(dummy_image_path)\n\n# Initialize DdddOcr for OCR recognition\n# It's recommended to initialize the object once, not in a loop.\nocr = ddddocr.DdddOcr()\n\n# Read the image bytes\nwith open(dummy_image_path, 'rb') as f:\n    image_bytes = f.read()\n\n# Perform OCR classification\nresult = ocr.classification(image_bytes)\nprint(f\"OCR Result: {result}\")\n\n# Clean up the dummy image\nos.remove(dummy_image_path)","lang":"python","description":"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."},"warnings":[{"fix":"Initialize the `ddddocr.DdddOcr()` object only once and reuse the instance for multiple recognition tasks.","message":"Initializing the `DdddOcr` object repeatedly (e.g., inside a loop) will significantly slow down performance due to model loading overhead.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that `ddddocr.DdddOcr()` is instantiated within each thread that requires OCR capabilities.","message":"When using `ddddocr` in a multi-threaded environment, each thread must create its own independent `DdddOcr` instance to prevent recognition errors or inconsistent results.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Rename your project directory to anything other than `ddddocr` to avoid conflicts with the installed package name.","message":"If your project directory (or a parent directory) is named `ddddocr`, you might encounter import conflicts, leading to `ModuleNotFoundError` or unexpected behavior.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Enabling 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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)`","cause":"The `DdddOcr` model is loaded during initialization, and repeated instantiation in a loop causes this overhead for each image.","error":"Initialization speed is slow when creating DdddOcr objects."},{"fix":"Rename your project directory to something other than `ddddocr`. This ensures that Python correctly imports the installed package.","cause":"Your project directory, or a directory in your `PYTHONPATH`, is likely named `ddddocr`, which conflicts with the installed library package name.","error":"ModuleNotFoundError: No module named 'ddddocr' (or similar import errors) OR unexpected behavior when importing ddddocr."},{"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.","cause":"The default OCR model might not be optimized for all types of complex or custom CAPTCHAs.","error":"OCR recognition accuracy is not as expected for specific CAPTCHAs."},{"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.","cause":"Initializing multiple `DdddOcr` instances with different functional parameters (e.g., one for OCR, another for detection) simultaneously.","error":"ddddocr uses too much memory when multiple functionalities are needed."},{"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.","cause":"This typically indicates an incompatibility between your CUDA/cuDNN installation and `onnxruntime`, or issues with `onnxruntime` dynamic link library (DLL) loading paths.","error":"Error: 'cuda may painc (exit code: 0xc000007b)' or missing DLL errors when using GPU acceleration."}]}