Install & Compatibility
Where this runs
tested against v0.7.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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.088s · 37.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.2s · import 0.083s · 39MB
36MB installed
● package 36MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ImageCaptcha
✓ from captcha.image import ImageCaptcha
✗ from captcha import ImageCaptcha
Import paths were restructured in v0.5.0; direct imports from `captcha` no longer work for image/audio modules.
AudioCaptcha
✓ from captcha.audio import AudioCaptcha
This quickstart demonstrates how to generate a simple image CAPTCHA. It initializes `ImageCaptcha` and then generates an image for a given text, saving it to a file. Note: Font paths may need adjustment based on your operating system. Audio captcha generation is also possible but requires additional dependencies (e.g., `pydub`, `ffmpeg`).
import os
from captcha.image import ImageCaptcha
# Generate an image captcha
image = ImageCaptcha(width=280, height=90, fonts=['/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf'])
# Fallback for systems where default font path might not exist
# For Windows: C:\Windows\Fonts\arial.ttf
# For macOS: /System/Library/Fonts/Arial.ttf
# For Linux: Check common paths like /usr/share/fonts/truetype
data = image.generate('1234')
output_filename = 'captcha_image.png'
image.write('1234', output_filename)
print(f"Generated captcha image: {output_filename}")
# Generate an audio captcha (requires 'pydub' and 'ffmpeg' or 'libav' for advanced audio formats)
# from captcha.audio import AudioCaptcha
# audio = AudioCaptcha()
# audio_filename = 'captcha_audio.wav'
# audio.write('1234', audio_filename)
# print(f"Generated captcha audio: {audio_filename}")
Debug
Known issues
breakingThe library underwent a significant code restructuring in version 0.5.0, which changed import paths for `ImageCaptcha` and `AudioCaptcha`.fixUpdate your import statements from `from captcha import ImageCaptcha` to `from captcha.image import ImageCaptcha` (and similarly for `AudioCaptcha`).
affects: <0.5.0
gotchaVersions prior to 0.7.1 used `secrets.randint` which was later replaced with more secure alternatives. While `secrets.randint` is generally secure, specific edge cases or platform behaviors might have been improved.fixUpgrade to `captcha>=0.7.1` to benefit from the latest security improvements in random number generation.
affects: <0.7.1
gotchaCompatibility with the `Pillow` library is crucial. `captcha` v0.7.0 included updates specifically for Pillow compatibility, indicating potential issues with older `Pillow` versions.fixEnsure you are using a compatible version of `Pillow`. The `captcha` library's `setup.py` generally specifies `Pillow>=8.2.0` for recent versions. Update `pip install --upgrade Pillow` if experiencing issues.
affects: All versions, especially >=0.7.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'captcha.image'
This typically occurs if you're using an outdated import path, trying to directly import `ImageCaptcha` or `AudioCaptcha` from the top-level `captcha` package after v0.5.0, or if the module name is misspelled.
fixChange your import statement to `from captcha.image import ImageCaptcha` (or `from captcha.audio import AudioCaptcha`). Ensure `captcha` is correctly installed.
ModuleNotFoundError: No module named 'PIL'
The `captcha` library relies on `Pillow` (a fork of PIL) for image manipulation. This error indicates `Pillow` is not installed.
fixInstall `Pillow` using `pip install Pillow`. If you have a legacy `PIL` installation, uninstall it and install `Pillow`.
OSError: cannot open resource
This error often occurs when `ImageCaptcha` cannot find the default font file (`arial.ttf`). This can happen on systems without the expected font path or if the specified font is missing.
fixSpecify a custom font path that exists on your system during `ImageCaptcha` initialization, e.g., `ImageCaptcha(fonts=['/path/to/your/custom_font.ttf'])`. Common font locations include `/usr/share/fonts/truetype` on Linux, `C:\Windows\Fonts` on Windows, or `/System/Library/Fonts` on macOS.
Upgrade
Version history
0.7.1latest on PyPI · released Mar 1, 2025
Audit
Dependencies
PillowrequiredRequired for image generation functionality; specifically Pillow>=8.2.0 is recommended for v0.7.0+.