Jak opravit chybu Django „ImproperlyConfigured: The SECRET_KEY Setting Must Not Be Empty“

Pokud Django vyvolá chybu django.core.exceptions.ImproperlyConfigured: The SECRET_KEY setting must not be empty, je okamžitý problém jednoduchý: modul nastavení, který Django načtl, neposkytuje v době běhu použitelnou hodnotu SECRET_KEY. Opravte hodnotu v modulu nastavení, který se skutečně používá, nebo se ujistěte, že proměnná prostředí, která ji poskytuje, dosáhne do procesu Django. Neřešte selhání v produkčním prostředí trvalým uložením tajného klíče do systému správy verzí.

Tato příručka byla ověřena oproti dokumentaci Django 6.1. Django 6.1 bylo vydáno 5. srpna 2026. Základní pravidlo je explicitní: SECRET_KEY má výchozí hodnotu prázdný řetězec, musí být unikátní a nepředvídatelný a Django odmítne spustit, pokud není nastaven. Podívejte se na oficiální referenci nastavení SECRET_KEY v Django.

Co vlastně znamená „SECRET_KEY setting must not be empty“?

Znamená to, že když se Django pokusilo použít settings.SECRET_KEY, vyhodnocená hodnota byla prázdná nebo jinak chyběla. U nově vytvořeného projektu příkaz django-admin startproject obvykle zapíše vygenerovaný klíč do souboru settings.py. Tato chyba je proto obzvláště častá poté, co byl projekt reorganizován pro více prostředí, přesunut na proměnné prostředí, nasazen na novou službu nebo spuštěn s jiným modulem nastavení.

První užitečná otázka není „Jak vymyslím libovolný řetězec, aby server naběhl?“. Je to „Odkud má toto nasazení získat svůj tajný klíč?“. Tento rozdíl je důležitý, protože existující produkční aplikace by měla obvykle obnovit svůj zamýšlený tajný klíč, nikoli tiše generovat jiný při každém spuštění.

Běžné vzory kódu, které způsobují tuto chybu

SECRET_KEY = ""

# Chybějící proměnná prostředí vrátí None
SECRET_KEY = os.getenv("SECRET_KEY")

# Chybějící proměnná prostředí tiše použije výchozí prázdný řetězec
SECRET_KEY = os.getenv("SECRET_KEY", "")

Všechny tři varianty nechají Django bez použitelného tajného klíče, pokud externí hodnota chybí. Pro produkční konfiguraci demonstruje vlastní kontrolní seznam nasazení Django formu fail-fast:

import os

SECRET_KEY = os.environ["SECRET_KEY"]

Při tomto vzoru chybějící proměnná prostředí procesu selže okamžitě, místo aby se tiše stala prázdnou hodnotou. Oficiální kontrolní seznam nasazení Django také uvádí, že produkční klíč by měl být velká náhodná hodnota, udržovaná v tajnosti, znovu nepoužívaná jinde a neukládaná do systému správy verzí.

Který soubor nastavení Django skutečně načítá?

Před úpravou souboru potvrďte, že jde o soubor, který používá váš příkaz nebo aplikační server. Django vybírá modul nastavení prostřednictvím DJANGO_SETTINGS_MODULE, což je cesta Pythonu, jako je mysite.settings nebo config.settings.production. Oficiální průvodce nastavením Django dokumentuje tento mechanismus a volitelný parametr příkazového řádku --settings.

Například změna config/settings.py nepomůže, pokud služba spouští Django s:

python manage.py runserver --settings=config.settings.local

>Stejně tak může produkční vstupní bod WSGI nebo ASGI nastavit jiný modul. Zkontrolujte manage.py, wsgi.py, asgi.py a skutečný příkaz serveru nebo konfiguraci služby. Pokud záměrně používáte produkční modul nastavení, testujte explicitně tento stejný modul, místo abyste testovali vývojový soubor a předpokládali, že výsledek platí i pro produkci.

Měli byste vygenerovat nový SECRET_KEY, nebo obnovit starý?

Pro zcela nový lokální projekt: vygenerování nové bezpečné hodnoty je rozumné. Standardní modul Pythonu secrets je navržen pro kryptograficky silnou náhodnost. Jeden přenosný příkaz je:

python -c "import secrets; print(secrets.token_urlsafe(64))"

Dokumentace Pythonu popisuje secrets jako modul pro generování bezpečných náhodných hodnot vhodných pro hesla, autentizační tokeny a související tajné údaje. Podívejte se na oficiální dokumentaci Pythonu secrets.

Pro existující produkční aplikaci, která dříve fungovala: nejprve se pokuste obnovit stejný zamýšlený tajný klíč z vašeho úložiště tajných údajů nebo konfigurace nasazení. Django používá SECRET_KEY pro kryptografické podepisování a pro několik funkcí, včetně určitých konfigurací relací a zpráv a tokenů pro resetování hesla. Neočekávaná výměna klíče může zneplatnit podepsaná data. Pokud starý klíč nebyl kompromitován a výpadek je pouze chybou v injektáži prostředí, jeho obnovení obvykle zamezí zbytečné rotaci.

Pokud byl starý klíč odhalen: proveďte jeho rotaci. Django 6.1 podporuje SECRET_KEY_FALLBACKS pro plánovanou rotaci, což umožňuje dočasně přijímat staré klíče, zatímco nové podepisování používá nový klíč. Odstraňte záložní klíče, jakmile skončí jejich přechodné období. Chování a kompromisy jsou zdokumentovány v oficiální referenci SECRET_KEY_FALLBACKS.

Jaká je nejrychlejší bezpečná oprava pro lokální vývoj?

Pokud se pouze snažíte spustit jednorázový lokální projekt, můžete vložit vygenerovanou hodnotu pouze pro vývoj do aktivního souboru nastavení dostatečně dlouho na potvrzení diagnózy:

SECRET_KEY = "nahraďte-toto-nahodnou-hodnotou-pouze-pro-vyvoj"

Poté znovu spusťte Django. Pokud chyba zmizí, potvrdili jste, že blokátor bylo prázdné nastavení. Nekopírujte produkční tajný klíč na vývojářský notebook jen pro pohodlné nastavení lokálního prostředí a nepovažujte pevně zakódovanou vývojovou hodnotu za svůj produkční návrh.

Dosahuje proměnná prostředí skutečně procesu Django?

Toto je nejdůležitější kontrola, pokud váš soubor nastavení již obsahuje SECRET_KEY = os.environ["SECRET_KEY"] nebo ekvivalentní vyhledávání. Proměnná musí existovat v prostředí přesného procesu, který importuje nastavení Django. Nastavení v jednom terminálu automaticky nevloží proměnnou do již běžící služby, kontejneru, správce procesů, úlohy CI nebo samostatného shellu.

Otestujte přítomnost bez vypsání samotného tajného klíče:

python -c "import os; print(bool(os.environ.get('SECRET_KEY')))"

Pokud toto vypíše False, opravte injektáž prostředí pro tento proces. Pro rychlý lokální test v shellu použijte syntaxi pro váš shell a poté spusťte Django ze stejného shellu. Například:

# Shell macOS / Linux
export SECRET_KEY='vas-vygenerovany-lokalni-tajny-klic'
python manage.py runserver

# Windows PowerShell
$env:SECRET_KEY = 'vas-vygenerovany-lokalni-tajny-klic'
python manage.py runserver

Pro produkci použijte mechanismus tajných údajů/konfigurace poskytnutý vaší hostingovou platformou nebo správcem procesů, místo abyste umisťovali hodnotu do příkazu, který by mohl být uložen v historii shellu.

Proč přidání SECRET_KEY do souboru .env neopravilo Django?

Soubor .env je pouze soubor, dokud něco nenačte jeho obsah do prostředí procesu nebo váš kód nastavení jej nepřečte. Oficiální příklad Django čte os.environ; Django nevyžaduje ani nedokumentuje vestavěný automatický krok načítání .env. Pokud váš projekt spoléhá na knihovnu dotenv, wrapper frameworku, konfiguraci kontejneru nebo platformu nasazení pro načtení tohoto souboru, ověřte tuto komponentu samostatně a ověřte, že běží předtím, než settings.py přečte SECRET_KEY.

Užitečným krokem je spustit výše uvedenou boolean kontrolu prostředí ze stejného kontejneru, účtu služby, shellu nebo fáze spuštění, která selhává. Pokud vypíše False, ladění obsahu settings.py samo o sobe nevyřeší problém s konfigurací na úrovni procesu.

Co když se chyba objeví pouze v Dockeru, CI, collectstatic, WSGI nebo ASGI?

To obvykle znamená, že jiný proces nebo fáze spuštění načítá projekt s jiným prostředím nebo modulem nastavení. Chyba se může objevit během collectstatic, migrací, testů, kontroly CI, startu aplikačního serveru nebo proces na pozadí, i když runserver funguje na vašem notebooku.

Nepředpokládejte, že tajný klíč dostupný v době běhu je také dostupný během sestavování obrazu nebo kroku CI. Naopak nepředpokládejte, že proměnná exportovaná v interaktivním shellu je viditelná pro systémovou službu. Zkontrolujte tato dvě fakta v kontextu selhání:

• Která hodnota DJANGO_SETTINGS_MODULE nebo --settings se používá?
• Má tento přesný proces neprázdnou proměnnou prostředí SECRET_KEY předtím, než Django importuje nastavení?

Konkrétní způsob injektáže tajného klíče závisí na Dockeru, vašem poskytovateli CI, vašem hostiteli nebo vašem správci procesů. Použijte oficiální mechanismus správy tajných údajů dané platformy. Požadavek na straně Django zůstává stejný: vybraná konfigurace nastavení musí poskytnout neprázdný tajný klíč v době běhu.

Jak ověříte opravu bez odhalení klíče?

Zaprvé, nevypisujte skutečný produkční klíč do logů jen proto, abyste dokázali, že existuje. Ověřte přítomnost pomocí boolean kontroly a poté nechte Django načíst konfiguraci:

python manage.py check

Pro produkční konfiguraci Django doporučuje spouštět kontroly nasazení proti produkčnímu souboru nastavení:

python manage.py check --deploy --settings=config.settings.production

Nahraďte cestu k modulu vaší skutečnou cestou k produkčnímu modulu nastavení. Oficiální kontrolní seznam nasazení konkrétně doporučuje check --deploy a varuje, že by měl být spuštěn proti produkčním nastavením.

Nakonec restartujte skutečný proces aplikace. Proměnná přidaná po spuštění služby obvykle neovlivní tento již běžící proces. Pokud restartovaný proces projde kontrolami Django a již nevyvolává výjimku, je problém s konfigurací vyřešen.

Které opravy byste se měli vyvarovat?

• Nenastavujte SECRET_KEY = "" ani nepoužívejte prázdnou výchozí hodnotu. To reprodukuje podmínku, kterou Django odmítá.
• Negenerujte nový klíč při každém spuštění aplikace. Měnící se klíč může zneplatnit podepsaná data a vytvořit nekonzistentní chování mezi více workerem.
• Nekopírujte tajný klíč z tutoriálu nebo jiného projektu. Django vyžaduje unikátní, nepředvídatelnou hodnotu a veřejná hodnota postrádá smysl tajného klíče.
• Neukládejte produkční klíč do Gitu. Kontrolní seznam nasazení Django explicitně doporučuje udržovat jej mimo systém správy verzí.
• Nevypisujte celý klíč do logů CI nebo produkce. Kontrolujte pouze to, zda je přítomen, pokud nemáte řízený postup auditu tajných údajů.
• Nepředpokládejte, že soubor .env je načten pouze proto, že existuje. Potvrďte mechanismus načítání a skutečné prostředí procesu.

Praktická cesta rozhodování

Situace	Nejlepší další krok
Nový lokální projekt a SECRET_KEY je doslova prázdný	Generujte bezpečnou vývojovou hodnotu, nastavte ji v aktivní konfiguraci nastavení a znovu spusťte Django.
Existující produkční aplikace náhle selže po nasazení	Zkontrolujte vybraný modul nastavení a obnovte zamýšlený tajný klíč z úložiště tajných údajů nasazení, než začnete uvažovat o rotaci.
os.getenv() nevrací žádnou hodnotu	Opravte injektáž prostředí pro přesný selhávající proces; vyhněte se záložní prázdné řetězcové hodnotě.
Soubor .env obsahuje klíč, ale Django stále selhává	Ověřte, že vaše startovací zásoba skutečně načítá tento soubor před importem nastavení.
Klíč mohl uniknout	Proveďte jeho rotaci záměrně; zvažte SECRET_KEY_FALLBACKS pro řízený přechod, kde je to vhodné.
Lokální server funguje, ale CI nebo produkce selhává	Porovnejte DJANGO_SETTINGS_MODULE a dostupnost tajného klíče v selhávajícím kontextu spuštění.

Závěrečný kontrolní seznam

• Potvrďte přesný modul nastavení, který Django načítá.
• Potvrďte, že SECRET_KEY se v tomto prostředí vyhodnocuje na neprázdnou hodnotu.
• Použijte unikátní, nepředvídatelnou hodnotu; znovu nepoužívejte veřejný nebo tutoriálový klíč.
• Udržujte produkční klíč mimo systém správy verzí.
• Pokud používáte proměnné prostředí, ujistěte se, že proměnná dosáhne do každého procesu, který importuje nastavení Django.
• Pokud používáte workflow .env, ověřte načítač, místo abyste předpokládali, že Django čte soubor automaticky.
• Obnovte starý produkční klíč, pokud je problém náhodná ztráta konfigurace; rotujte pouze záměrně nebo pokud je to vyžadováno.
• Spusťte python manage.py check a pro produkci spusťte check --deploy proti produkčnímu modulu nastavení.
• Po změně prostředí restartujte skutečnou službu.

Klíčovým bodem je, že tato výjimka nežádá o konkrétní magický řetězec. Říká vám, že aktivní nastavení Django neobsahují použitelný tajný klíč. Opravte zdroj této konfigurace, zachovejte zamýšlený produkční klíč, kde je to vhodné, a ověřte výsledek ve stejném prostředí procesu, který původně selhal.