Ошибка ModuleNotFoundError: No module named 'captcha' в Django reCAPTCHA — как исправить

Почему при интеграции django-recaptcha появляется ModuleNotFoundError: No module named 'captcha', и как исправить запись INSTALLED_APPS на django_recaptcha.

Интеграция Google reCAPTCHA в форму Django может сорваться уже на самом первом шаге — при запуске сервера. Характерный признак — длинный traceback, завершающийся ошибкой ModuleNotFoundError: No module named 'captcha', хотя django-recaptcha установлен и импорты в форме выглядят верно. Проблема не в ключах или шаблонах; дело в названии приложения, которое Django пытается импортировать.

Минимальная конфигурация, приводящая к сбою

Ниже показана настройка, которая на первый взгляд кажется правильной. Пакет django-recaptcha установлен, импорты в форме идут из django_recaptcha, а в списке приложений есть, как кажется, нужное приложение captcha:

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'support',
    'captcha',
]

from django import forms
from django_recaptcha.fields import ReCaptchaField
from django_recaptcha.widgets import ReCaptchaV2Checkbox

class SupportForm(forms.Form):
    user_email = forms.EmailField()
    message_text = forms.CharField(widget=forms.Textarea)
    spam_check = ReCaptchaField(widget=ReCaptchaV2Checkbox)

Несмотря на корректные импорты в форме, runserver падает во время заполнения реестра приложений с ошибкой ModuleNotFoundError: No module named 'captcha'.

В чём суть ошибки

Django загружает каждый элемент из INSTALLED_APPS, пытаясь его импортировать. Дойдя до 'captcha', он выполняет import_module('captcha') и терпит неудачу, потому что установленный модуль называется иначе. Установленный пакет — django-recaptcha, а импортируемое приложение — django_recaptcha. Несоответствие между записью в INSTALLED_APPS и реальным именем модуля и является единственной причиной ошибки.

«имя приложения должно быть django_recaptcha согласно инструкции»

Как исправить

Укажите в INSTALLED_APPS настоящее имя модуля. Больше в показанной конфигурации менять ничего не нужно.

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'support',
    'django_recaptcha',
]

Код формы уже согласован с django_recaptcha, поэтому его можно оставить без изменений:

from django import forms
from django_recaptcha.fields import ReCaptchaField
from django_recaptcha.widgets import ReCaptchaV2Checkbox

class SupportForm(forms.Form):
    user_email = forms.EmailField()
    message_text = forms.CharField(widget=forms.Textarea)
    spam_check = ReCaptchaField(widget=ReCaptchaV2Checkbox)

Почему это важно

В Django часто путают три разных имени: название пакета в pip, путь импорта в Python и метку приложения в INSTALLED_APPS. django-recaptcha — это пакет, который вы устанавливаете; django_recaptcha — модуль, который Django должен импортировать при запуске; а попытка использовать другое слово, например captcha, заставляет Django импортировать не то и мгновенно падает. Просмотр последней строки traceback обычно точно показывает, какое имя Django не смог импортировать.

Итог

Если свежая интеграция падает при старте с ModuleNotFoundError, сравните запись в INSTALLED_APPS с фактическим путём модуля из рабочих импортов. Для django-recaptcha правильное имя приложения в списке — django_recaptcha. Достаточно привести эти названия к одному виду — и сервер запустится, после чего можно продолжить с валидацией формы и проверками reCAPTCHA.