Captcha Generator

0.7.1 · active · verified Thu Apr 16

The `captcha` library (current version 0.7.1) is a Python utility designed to generate both image and audio CAPTCHAs. It provides a simple API to create various forms of captchas, useful for preventing bots in web applications. The library is actively maintained with regular releases addressing features, bug fixes, and security enhancements.

Common errors

```
ModuleNotFoundError: No module named 'captcha.image'
```
cause 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.

fix Change 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'
```
cause The `captcha` library relies on `Pillow` (a fork of PIL) for image manipulation. This error indicates `Pillow` is not installed.

fix Install `Pillow` using `pip install Pillow`. If you have a legacy `PIL` installation, uninstall it and install `Pillow`.
```
OSError: cannot open resource
```
cause 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.

fix Specify 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.

Warnings

breaking The library underwent a significant code restructuring in version 0.5.0, which changed import paths for `ImageCaptcha` and `AudioCaptcha`.
Fix: Update your import statements from `from captcha import ImageCaptcha` to `from captcha.image import ImageCaptcha` (and similarly for `AudioCaptcha`).
gotcha Versions 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.
Fix: Upgrade to `captcha>=0.7.1` to benefit from the latest security improvements in random number generation.
gotcha Compatibility with the `Pillow` library is crucial. `captcha` v0.7.0 included updates specifically for Pillow compatibility, indicating potential issues with older `Pillow` versions.
Fix: Ensure 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.

Install

pip install captcha Install stable version

Imports

ImageCaptcha
wrong:
```
from captcha import ImageCaptcha
```
correct:
```
from captcha.image 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
```

Quickstart

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}")

view raw JSON →