Så åtgärdar du Django-felet “ImproperlyConfigured: The SECRET_KEY Setting Must Not Be Empty”

Om Django kastar felet django.core.exceptions.ImproperlyConfigured: The SECRET_KEY setting must not be empty är det omedelbara problemet enkelt: den inställningsmodul som Django laddade in tillhandahåller inte ett användbart SECRET_KEY-värde vid körning. Åtgärda värdet i den inställningsmodul som faktiskt används, eller se till att miljövariabeln som tillhandahåller det når Django-processen. Lös inte ett produktionsfel genom att committa en permanent hemlighet till versionshantering.

Den här guiden har kontrollerats mot Django 6.1-dokumentationen. Django 6.1 släpptes den 5 augusti 2026. Grundregeln är uttrycklig: SECRET_KEY har som standard en tom sträng, måste vara unik och oförutsägbar, och Django vägrar starta om den inte är inställd. Se den officiella referensen för Django SECRET_KEY-inställningen.

Vad betyder “SECRET_KEY setting must not be empty” egentligen?

Det betyder att när Django försökte använda settings.SECRET_KEY var det lösta värdet tomt eller på annat sätt saknat. I ett nyskapat projekt skriver django-admin startproject normalt in en genererad nyckel i settings.py. Felet är därför särskilt vanligt efter att ett projekt har omorganiserats för flera miljöer, flyttats till miljövariabler, distribuerats till en ny tjänst eller startats med en annan inställningsmodul.

Den första användbara frågan är inte “Hur hittar jag på vilken sträng som helst som får servern att starta?” Det är “Var ska den här distributionen hämta sin hemlighet från?” Den distinktionen är viktig eftersom en befintlig produktionsapplikation normalt bör återställa sin avsedda hemlighet snarare än att tyst generera en annan vid varje start.

Vanliga kodmönster som orsakar felet

SECRET_KEY = ""

# Saknad miljövariabel returnerar None
SECRET_KEY = os.getenv("SECRET_KEY")

# Saknad miljövariabel faller tyst tillbaka till en tom sträng
SECRET_KEY = os.getenv("SECRET_KEY", "")

Alla tre lämnar Django utan en användbar hemlighet när det externa värdet saknas. För en produktionskonfiguration demonstrerar Djangos egen distributionschecklista ett fail-fast-formulär:

import os

SECRET_KEY = os.environ["SECRET_KEY"]

Med detta mönster misslyckas en saknad processmiljövariabel omedelbart istället för att tyst bli ett tomt värde. Den officiella Django-distributionschecklistan säger också att produktionsnyckeln bör vara ett stort slumpmässigt värde, hållas hemligt, inte återanvändas någon annanstans och inte committas till versionshantering.

Vilken inställningsfil laddar Django egentligen?

Innan du redigerar en fil, bekräfta att det är den fil som ditt kommando eller din applikationsserver använder. Django väljer en inställningsmodul via DJANGO_SETTINGS_MODULE, en Python-sökväg som mysite.settings eller config.settings.production. Den officiella Django-inställningsguiden dokumenterar denna mekanism och kommandoradsalternativet --settings.

Exempelvis hjälper det inte att ändra config/settings.py om tjänsten startar Django med:

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

På samma sätt kan en produktions WSGI- eller ASGI-ingångspunkt ange en annan modul. Inspektera manage.py, wsgi.py, asgi.py och det faktiska serverkommandot eller tjänstekonfigurationen. Om du avsiktligt använder en produktionsinställningsmodul, testa den modulen explicit istället för att testa en utvecklingsfil och anta att resultatet överförs.

Bör du generera en ny SECRET_KEY eller återställa den gamla?

För ett helt nytt lokalt projekt: att generera ett nytt säkert värde är rimligt. Pythons standardmodul secrets är designad för kryptografiskt stark slumpmässighet. Ett portabelt kommando är:

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

Python-dokumentationen beskriver secrets som modulen för att generera säkra slumpmässiga värden lämpliga för lösenord, autentiseringstokens och relaterade hemligheter. Se den officiella Python secrets-dokumentationen.

För en befintlig produktionsapplikation som tidigare fungerade: försök först att återställa samma avsedda hemlighet från din hemlighetslagring eller distributionskonfiguration. Django använder SECRET_KEY för kryptografisk signering och för flera funktioner, inklusive vissa sessions- och meddelandekonfigurationer och lösenordsåterställningstokens. Att oväntat ersätta nyckeln kan ogiltigförklara signerad data. Om den gamla nyckeln inte var komprometterad och avbrottet bara är ett misstag vid miljöinjektion, undviker återställning av den vanligtvis en onödig rotation.

Om den gamla nyckeln exponerades: rotera den. Django 6.1 stöder SECRET_KEY_FALLBACKS för planerad rotation, vilket tillåter gamla nycklar att accepteras tillfälligt medan ny signering använder den nya nyckeln. Ta bort fallback-nycklar när deras övergångsperiod är över. Beteendet och avvägningen dokumenteras i den officiella SECRET_KEY_FALLBACKS-referensen.

Vad är den snabbaste säkra åtgärden för lokal utveckling?

Om du bara försöker få igång ett engångslokalt projekt kan du sätta ett genererat utvecklingsvärde i den aktiva inställningsfilen tillräckligt länge för att bekräfta diagnosen:

SECRET_KEY = "replace-this-with-a-random-development-only-value"

Starta sedan Django igen. Om felet försvinner har du bekräftat att den tomma inställningen var hindret. Kopiera inte en produktionshemlighet till en utvecklarlaptop bara för att göra lokal installation bekväm, och behandla inte ett hårdkodat utvecklingsvärde som din produktionsdesign.

Når miljövariabeln verkligen Django-processen?

Detta är den viktigaste kontrollen när din inställningsfil redan innehåller SECRET_KEY = os.environ["SECRET_KEY"] eller en motsvarande uppslagning. Variabeln måste finnas i miljön för den exakta process som importerar Django-inställningar. Att ställa in den i en terminal placerar den inte automatiskt i en redan körande tjänst, container, processhanterare, CI-jobb eller separat shell.

Testa närvaro utan att skriva ut själva hemligheten:

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

Om detta skriver ut False, åtgärda miljöinjektionen för den processen. För ett snabbt lokalt shell-test, använd syntaxen för ditt shell och starta sedan Django från samma shell. Till exempel:

# macOS / Linux shell
export SECRET_KEY='your-generated-local-secret'
python manage.py runserver

# Windows PowerShell
$env:SECRET_KEY = 'your-generated-local-secret'
python manage.py runserver

För produktion, använd den hemlighets-/konfigurationsmekanism som tillhandahålls av din hostingplattform eller processhanterare istället för att placera värdet i ett kommando som kan lagras i shellhistorik.

Varför löste inte tillägget av SECRET_KEY i en .env-fil Django?

En .env-fil är bara en fil tills något laddar dess innehåll till processmiljön eller din inställningskod läser den. Djangos officiella exempel läser os.environ; Django kräver eller dokumenterar inte ett inbyggt automatiskt .env-laddningssteg. Om ditt projekt förlitar sig på ett dotenv-bibliotek, ramverkshölje, containerkonfiguration eller distributionsplattform för att ladda den filen, verifiera den komponenten separat och verifiera att den körs innan settings.py läser SECRET_KEY.

En användbar åtgärd är att köra den booleska miljökontrollen ovan från samma container, tjänstekonto, shell eller exekveringsstadium som misslyckas. Om den skriver ut False kommer felsökning av innehållet i settings.py ensam inte att lösa processnivåkonfigurationsproblemet.

Vad händer om felet endast visas i Docker, CI, collectstatic, WSGI eller ASGI?

Det betyder vanligtvis att en annan process eller exekveringsstadium laddar projektet med en annan miljö eller inställningsmodul. Felet kan dyka upp under collectstatic, migrationer, tester, ett CI-kontroll, start av applikationsserver eller en bakgrundsprocess även om runserver fungerar på din laptop.

Anta inte att en hemlighet som är tillgänglig vid körning också är tillgänglig under en image-build eller CI-steg. Omvänt, anta inte att en variabel exporterad i ett interaktivt shell är synlig för en systemtjänst. Kontrollera dessa två fakta i den misslyckade kontexten:

• Vilket DJANGO_SETTINGS_MODULE eller --settings-värde används?
• Har den exakta processen en icke-tom SECRET_KEY-miljövariabel innan Django importerar inställningar?

Det specifika sättet att injicera en hemlighet beror på Docker, din CI-leverantör, din värd eller din processhanterare. Använd den plattformens officiella hemlighetsförvaltningsmekanism. Kravet på Django-sidan förblir detsamma: den valda inställningskonfigurationen måste tillhandahålla en icke-tom hemlighet vid körning.

Hur verifierar du åtgärden utan att exponera nyckeln?

Först, skriv inte ut den faktiska produktionsnyckeln i loggar bara för att bevisa att den finns. Verifiera närvaro med en boolesk kontroll, låt sedan Django ladda konfigurationen:

python manage.py check

För en produktionskonfiguration rekommenderar Django att köra distributionskontroller mot produktionsinställningsfilen:

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

Ersätt modulvägen med din riktiga produktionsinställningsmodul. Den officiella distributionschecklistan rekommenderar specifikt check --deploy och varnar för att den bör köras mot produktionsinställningar.

Slutligen, starta om den faktiska applikationsprocessen. En variabel som lagts till efter att en tjänst startade påverkar vanligtvis inte den redan körande processen. Om den omstartade processen klarar Djangos kontroller och inte längre kastar undantaget, är konfigurationsproblemet löst.

Vilka åtgärder bör du undvika?

• Ställ inte in SECRET_KEY = "" eller använd ett tomt standardvärde. Det reproducerar tillståndet som Django avvisar.
• Generera inte en ny nyckel vid varje applikationsstart. En ändrande nyckel kan ogiltigförklara signerad data och skapa inkonsekvent beteende över flera arbetare.
• Kopiera inte en hemlighet från en handledning eller ett annat projekt. Django kräver ett unikt, oförutsägbart värde, och ett offentligt värde förlorar syftet med en hemlighet.
• Committa inte produktionsnyckeln till Git. Djangos distributionschecklista råder uttryckligen att hålla den utanför versionshantering.
• Skriv inte ut hela nyckeln i CI- eller produktionsloggar. Kontrollera bara om den finns om du inte har en kontrollerad hemlighetsrevisionsprocedur.
• Anta inte att en .env-fil laddas bara för att den finns. Bekräfta laddningsmekanismen och den faktiska processmiljön.

En praktisk beslutsväg

Slutgiltig checklista

• Bekräfta den exakta inställningsmodulen Django laddar.
• Bekräfta att SECRET_KEY löser till ett icke-tomt värde i den miljön.
• Använd ett unikt, oförutsägbart värde; återanvänd inte en offentlig eller handledningsnyckel.
• Håll produktionsnyckeln utanför versionshantering.
• Om du använder miljövariabler, se till att variabeln når varje process som importerar Django-inställningar.
• Om du använder ett .env-arbetsflöde, verifiera laddaren istället för att anta att Django läser filen automatiskt.
• Återställ den gamla produktionsnyckeln om problemet är oavsiktlig konfigurationsförlust; rotera endast när det är avsiktligt eller nödvändigt.
• Kör python manage.py check, och för produktion kör check --deploy mot produktionsinställningsmodulen.
• Starta om den faktiska tjänsten efter att ha ändrat dess miljö.

Den viktigaste punkten är att detta undantag inte ber om en specifik magisk sträng. Det säger dig att Djangos aktiva inställningar inte innehåller en användbar hemlighet. Åtgärda källan till den konfigurationen, bevara den avsedda produktionsnyckeln när det är lämpligt, och verifiera resultatet i samma processmiljö som ursprungligen misslyckades.