DRF reCAPTCHA

4.0.3 verified Fri May 01 auth: no python

A Django REST Framework field and serializer for Google reCAPTCHA (v2 and v3) verification. Current version 4.0.3 supports Django ≥4.2, Python ≥3.10, DRF ≥3.14. Released irregularly; latest updates add Django 5.2 and Python 3.13 support.

pip install drf-recaptcha

Common errors

error AttributeError: module 'drf_recaptcha' has no attribute 'ReCaptchaSerializer' ↓

cause Importing from top-level package instead of submodule.

fix

Use from drf_recaptcha.serializers import ReCaptchaSerializer.

error django.core.exceptions.ImproperlyConfigured: Requested setting DRF_RECAPTCHA_SECRET_KEY, but settings are not configured. ↓

cause Missing Django settings configuration or missing env variable.

fix

Ensure DRF_RECAPTCHA_SECRET_KEY is set in Django settings (e.g., os.environ.get('RECAPTCHA_SECRET_KEY')). For quick tests, configure settings before using the serializer.

error ValidationError: ['This field is required.'] on recaptcha field ↓

cause The `recaptcha` field is required by default and missing from request data.

fix

Include the 'g-recaptcha-response' token from the client in your request data under the key recaptcha.

error TypeError: __init__() got an unexpected keyword argument 'score' ↓

cause The `ReCaptchaV2Field` does not accept a `score` argument (only v3 fields do).

fix

Use ReCaptchaV3Field for score-based verification, or remove the score argument from ReCaptchaV2Field.

error ValueError: Invalid version: specify 'v2' or 'v3' ↓

cause A wrong value passed to the `version` parameter of `ReCaptchaField`.

fix

Set version='v2' or version='v3' (string). Default is 'v2'.

Warnings

breaking Version 4.0.0 drops support for Django 3.2, 4.0, 4.1; Python 3.8, 3.9; and DRF 3.11, 3.12, 3.13. Upgrade your environment if migrating from <4.0. ↓

fix Ensure Django ≥4.2, Python ≥3.10, DRF ≥3.14 before upgrading to drf-recaptcha ≥4.0.

gotcha The `ReCaptchaSerializer` includes a `recaptcha` field by default but does not hide it from the serializer output. This field will be serialized back to the client unless explicitly excluded using `exclude` or `fields`. ↓

fix Add `Meta.exclude = ['recaptcha']` or use `fields` to limit output fields.

gotcha In reCAPTCHA v3, the default required score is 0.5. Setting the required score to 0 (to allow all) was broken before version 3.2.0; the score 0 was treated as None and overridden to 0.5. ↓

fix Upgrade to ≥3.2.0 if you need a required score of 0. Now a score of 0 correctly allows all traffic.

deprecated The setting `DRF_RECAPTCHA_TESTING` when set to `True` skips actual verification. However, the field will still require a non-empty string. This is intended for testing but may confuse users expecting full bypass. ↓

fix Use `DRF_RECAPTCHA_TESTING=True` only in test environments; for real bypass consider using a mock serializer.

gotcha Multiple/ dynamic secret keys (introduced in 3.0.0) require passing a secret key via the serializer's `context` or field kwargs. If not provided, the default `DRF_RECAPTCHA_SECRET_KEY` is used. Forgetting this can lead to wrong key usage. ↓

fix Always pass the intended secret key explicitly when using multiple keys: `ReCaptchaField(secret_key='...')`.

Imports

ReCaptchaSerializer

wrong

from drf_recaptcha import ReCaptchaSerializer

correct

from drf_recaptcha.serializers import ReCaptchaSerializer

Import from the serializers submodule, not top-level package

ReCaptchaField

wrong

from drf_recaptcha import ReCaptchaField

correct

from drf_recaptcha.fields import ReCaptchaField

Field class is in the fields submodule

Quickstart

Quickstart: define a serializer inheriting ReCaptchaSerializer. Configure DRF_RECAPTCHA_SECRET_KEY in Django settings. For testing, set DRF_RECAPTCHA_TESTING=True to bypass verification.

import os
from django.conf import settings
from rest_framework import serializers
from drf_recaptcha.serializers import ReCaptchaSerializer

settings.configure(
    DRF_RECAPTCHA_SECRET_KEY=os.environ.get('RECAPTCHA_SECRET_KEY', 'test-secret'),
    INSTALLED_APPS=['django.contrib.contenttypes', 'django.contrib.auth'],
    DATABASES={'default': {'ENGINE': 'django.db.backends.sqlite3', 'NAME': ':memory:'}},
)
import django
django.setup()

class MySerializer(ReCaptchaSerializer):
    email = serializers.EmailField()

# Dummy data for testing (use valid reCAPTCHA response in production)
data = {'email': 'test@example.com', 'recaptcha': 'dummy-response'}
serializer = MySerializer(data=data)
print(serializer.is_valid())