python-dotenv ne charge pas vos variables : la réparation rapide, cause par cause

    20 novembre 2026
    10 min de lecture
    Par Orson Vale
    Partager cet article

    Vous ajoutez load_dotenv() en haut de main.py, vous lancez le script, et os.getenv("API_KEY") renvoie None. Vous ajoutez un print(load_dotenv()) : il affiche True. Le fichier .env est là, à côté du code, avec la bonne clé. C'est précisément la situation où l'on perd une heure, parce que la fonction a l'air de fonctionner.

    Elle fonctionne, d'ailleurs : elle applique des règles que peu de gens lisent, sur l'endroit où elle cherche le fichier, sur ce qu'elle fait quand une variable existe déjà et sur le moment où votre code lit l'environnement.

    La réparation est rapide une fois la cause isolée. Les causes, elles, se rangent en cinq familles, et on peut les éliminer dans l'ordre en moins de cinq minutes.

    Ce que load_dotenv fait réellement quand on l'appelle sans argument

    Sans argument, load_dotenv() appelle find_dotenv(). Cette fonction ne part pas du répertoire courant du terminal. Elle part du répertoire du fichier Python qui a appelé load_dotenv(), puis remonte de dossier parent en dossier parent jusqu'à la racine du disque, et s'arrête au premier fichier nommé .env rencontré. Le répertoire courant n'est utilisé qu'en mode interactif, par exemple dans une console Python ou un notebook, ou si l'on passe usecwd=True.

    Deuxième règle, la plus souvent oubliée : le paramètre override vaut False par défaut. Si une variable existe déjà dans os.environ au moment de l'appel, la valeur du fichier est ignorée sans avertissement. C'est un choix de conception défendable, puisque l'environnement réel doit l'emporter sur un fichier de développement, mais il produit des symptômes déroutants.

    Troisième règle : la valeur de retour ne dit pas ce que l'on croit. Dans les versions 1.x, load_dotenv() renvoie False quand aucun fichier n'est trouvé ou quand le fichier ne contient aucune variable. Elle renvoie True dès que le fichier contient au moins une variable, même si toutes ont été ignorées parce qu'elles existaient déjà. Un True prouve donc que le fichier a été lu, pas que vos valeurs sont en place.

    from dotenv import load_dotenv, find_dotenv
    import os
    
    chemin = find_dotenv()
    print("fichier trouvé :", repr(chemin))          # chaîne vide si rien n'est trouvé
    print("lu :", load_dotenv(chemin, verbose=True))
    print("API_KEY :", repr(os.getenv("API_KEY")))
    

    Ces trois lignes d'affichage tranchent déjà la moitié des cas. Si chemin est une chaîne vide, le problème est la recherche du fichier. Si le chemin est le bon mais que la valeur affichée diffère de celle du fichier, le problème est l'écrasement ou l'ordre d'exécution. Si la variable vaut None alors que le fichier est trouvé, le problème est la lecture du fichier. L'option verbose=True ajoute un message dans les journaux quand le fichier est introuvable, ce qui suffit souvent à repérer une faute dans le chemin.

    Un dernier contrôle évite une fausse piste : pip show python-dotenv doit afficher le paquet. Le nom d'import est dotenv, mais le paquet à installer s'appelle python-dotenv. Un autre paquet portant le nom dotenv a existé sur PyPI, et l'installer par erreur donne des comportements incohérents.

    Le fichier n'est pas trouvé : suivre le chemin de recherche à la main

    Le cas le plus fréquent concerne les projets organisés en sous-dossiers. Prenons une structure réaliste. Le fichier .env se trouve dans /srv/app. Le code qui appelle load_dotenv() se trouve dans /srv/app/src/api/routes/users.py. La recherche commence dans /srv/app/src/api/routes, puis passe à /srv/app/src/api, puis à /srv/app/src, et trouve le fichier au quatrième niveau, dans /srv/app. Tout fonctionne.

    Déplacez maintenant le fichier de configuration dans /srv/config/.env, une pratique courante sur les serveurs. La recherche remonte jusqu'à /srv, puis /, en six étapes, et ne passe jamais par /srv/config, qui est un dossier frère et non un parent. Résultat : chaîne vide, aucune variable chargée, et aucun message d'erreur si verbose est resté à False.

    Le piège inverse existe aussi. Un module de configuration installé comme paquet dans un environnement virtuel, par exemple dans site-packages, appelle load_dotenv(). La recherche part alors du dossier du paquet installé, quelque part dans .venv/lib/python3.12/site-packages/, et remonte. Elle peut trouver le .env du projet par chance, si l'environnement virtuel est dans le projet, ou ne rien trouver si l'environnement est ailleurs, comme c'est le cas avec Poetry ou pipx par défaut.

    La solution la plus robuste consiste à ne pas dépendre de la recherche : construire un chemin explicite à partir du fichier courant.

    from pathlib import Path
    from dotenv import load_dotenv
    
    RACINE = Path(__file__).resolve().parents[3]   # remonte de 3 niveaux
    load_dotenv(RACINE / ".env")
    

    Le chiffre passé à parents doit correspondre à la profondeur réelle du fichier. Une alternative plus lisible pour les scripts lancés depuis la racine du projet est load_dotenv(find_dotenv(usecwd=True)), qui part du répertoire courant. Elle casse en revanche dès qu'on lance le script depuis un autre dossier, par exemple dans une tâche cron.

    Pour les fichiers de configuration multiples, on peut charger plusieurs fichiers dans l'ordre : d'abord .env, puis .env.local avec override=True, pour que les valeurs locales l'emportent.

    Le fichier est lu, mais la valeur reste l'ancienne

    Ce cas produit le symptôme du début de l'article : True à l'affichage, valeur inchangée. Il a deux causes distinctes.

    La première est une variable déjà définie dans l'environnement. Exemple chiffré : un développeur a ajouté il y a trois mois export DB_POOL_SIZE=5 dans son ~/.bashrc pour un autre projet. Le fichier .env de son nouveau projet contient DB_POOL_SIZE=20. Il lance l'application, qui ouvre 5 connexions au lieu de 20, et les tests de charge plafonnent à environ 5 requêtes simultanées vers la base. load_dotenv() renvoie True, puisque le fichier contient quatre variables.

    Trois d'entre elles sont appliquées, la quatrième est ignorée parce qu'elle existait déjà. Un echo $DB_POOL_SIZE dans le terminal affiche 5 et révèle la cause en deux secondes. Deux corrections possibles : supprimer la ligne du ~/.bashrc, ou passer override=True. La seconde est tentante, mais elle inverse la priorité pour toutes les variables, y compris en production si le fichier y est déployé par erreur.

    La seconde cause est l'ordre d'exécution. Beaucoup de projets lisent la configuration au moment de l'import d'un module.

    import os                                  # fichier config.py
    DATABASE_URL = os.getenv("DATABASE_URL")   # lu à l'import
    
    import config            # fichier main.py : DATABASE_URL vaut déjà None
    from dotenv import load_dotenv
    load_dotenv()            # trop tard pour config.py
    

    Ici, load_dotenv() fonctionne parfaitement, mais config.DATABASE_URL a été figé avant son appel. Les outils de tri automatique des imports, comme isort ou Ruff, aggravent le problème : ils remontent les imports en haut du fichier et peuvent placer import config avant l'appel à load_dotenv(), même si le développeur avait écrit l'ordre correct. La correction consiste à appeler load_dotenv() dans config.py lui-même, juste avant les lectures, ou dans le point d'entrée avant tout import qui lit l'environnement, avec un commentaire qui désactive le tri pour cette ligne.

    Avec Django, l'appel se place en haut de settings.py. Avec FastAPI et pydantic-settings, le champ env_file de la configuration du modèle charge le fichier lui-même, et un load_dotenv() ajouté en plus n'est utile que pour les modules qui lisent os.environ directement.

    Le fichier est trouvé, mais il est mal lu

    Troisième famille : le fichier existe, il est trouvé, et la variable reste absente ou prend une valeur bizarre. Quatre causes reviennent.

    Le nom du fichier d'abord. Sous Windows, l'explorateur masque les extensions connues par défaut. Un fichier créé avec le Bloc-notes et nommé .env peut s'appeler en réalité .env.txt. Un dir /a en ligne de commande ou un ls -la sous WSL affiche le vrai nom.

    L'encodage ensuite. Certains éditeurs ajoutent une marque d'ordre des octets (BOM) au début des fichiers UTF-8. Lu en UTF-8 simple, ce caractère invisible peut se coller au premier nom de clé : la variable s'appelle alors API_KEY et non API_KEY. Seule la première ligne du fichier est touchée, ce qui donne un symptôme très particulier : toutes les variables se chargent sauf la première. Charger avec encoding="utf-8-sig" ou réenregistrer le fichier sans BOM règle le problème.

    La syntaxe, troisièmement. python-dotenv accepte CLE=valeur, les espaces autour du signe égal, le préfixe export, les guillemets simples ou doubles et les commentaires commençant par #. Une valeur contenant un # sans guillemets peut être tronquée, et une valeur sur plusieurs lignes doit être entre guillemets. Les mots de passe générés automatiquement contiennent souvent #, $ ou des guillemets : la valeur chargée a alors quelques caractères de moins que l'originale. Comparer len(os.getenv("DB_PASSWORD")) avec la longueur attendue détecte la troncature sans afficher le secret.

    Enfin, le type. Une variable d'environnement est toujours une chaîne. DEBUG=False dans le fichier donne la chaîne "False", qui vaut vrai dans un test if. Le fichier est bien chargé, mais le comportement donne l'impression du contraire. Il faut convertir explicitement, par exemple avec os.getenv("DEBUG", "false").lower() in ("1", "true", "yes").

    Quand l'environnement d'exécution ignore votre .env

    La dernière famille ne relève pas de python-dotenv mais de l'endroit où le code tourne. Le script marche sur le poste de développement et échoue ailleurs, ou l'inverse.

    Docker est la première source de confusion. Le fichier .dockerignore exclut souvent .env, ce qui est une bonne pratique pour ne pas embarquer de secrets dans l'image, mais alors le fichier n'existe pas dans le conteneur.

    Docker Compose ajoute un piège : le fichier .env placé à côté de compose.yaml sert à substituer des variables dans le fichier Compose lui-même, pas à les injecter dans le conteneur. Pour qu'elles arrivent dans le processus Python, il faut une directive env_file ou environment dans la définition du service. Dans ce cas, load_dotenv() est inutile dans le conteneur : les variables sont déjà là.

    VS Code produit le piège inverse. L'extension Python lit par défaut le fichier désigné par le réglage python.envFile, qui pointe vers ${workspaceFolder}/.env, et injecte ses variables dans les sessions de débogage. Le code fonctionne donc dans le débogueur même sans load_dotenv(), puis échoue dès qu'on le lance dans un terminal ordinaire.

    Les notebooks Jupyter utilisent le répertoire du notebook comme répertoire courant, et l'extension IPython fournie par python-dotenv permet d'écrire %load_ext dotenv puis %dotenv dans une cellule. Un notebook rouvert après un changement du fichier garde les anciennes valeurs tant que le noyau n'est pas redémarré, puisque override reste à False.

    Les tâches planifiées, enfin. Cron lance les scripts avec un environnement minimal et un répertoire courant qui est souvent le dossier personnel de l'utilisateur. Un find_dotenv(usecwd=True) y échoue systématiquement. Avec systemd, la directive EnvironmentFile du service charge les variables avant le démarrage du processus, ce qui rend load_dotenv() superflu.

    L'arbre de décision en cinq minutes, et le verdict

    Les familles précédentes se testent dans un ordre précis, du plus fréquent au plus rare. Chaque question prend moins d'une minute.

    1. find_dotenv() renvoie-t-il une chaîne vide ? Oui : le fichier n'est pas trouvé. Vérifiez le vrai nom du fichier (.env.txt), puis passez un chemin explicite construit avec Path(__file__). Non : question 2.
    2. La variable a-t-elle une valeur dans le terminal avant le lancement (echo $VAR ou echo %VAR%) ? Oui : elle est déjà définie et le fichier est ignoré pour elle. Supprimez la définition du shell ou utilisez override=True en connaissance de cause. Non : question 3.
    3. Le module qui lit la variable est-il importé avant l'appel à load_dotenv() ? Oui : déplacez l'appel dans le module de configuration. Non : question 4.
    4. Toutes les variables se chargent-elles sauf la première ? Oui : BOM, rechargez avec encoding="utf-8-sig". Non : question 5.
    5. La valeur chargée est-elle plus courte que prévu ou mal interprétée ? Oui : guillemets autour des valeurs contenant #, $ ou des espaces, et conversion explicite des booléens. Non : question 6.
    6. Le code tourne-t-il dans Docker, sous cron, sous systemd ou dans un débogueur ? Oui : l'environnement d'exécution décide, configurez-le à son niveau plutôt qu'avec un fichier .env.

    Reste la question de fond : faut-il garder python-dotenv dans le code de production ? Le gain est réel en développement, où un fichier unique remplace une dizaine d'export à retaper. Le coût apparaît en production, où un .env oublié sur un serveur peut injecter des valeurs de test, et où les plateformes d'hébergement, les orchestrateurs et les gestionnaires de secrets fournissent déjà les variables.

    Le compromis le plus sain consiste à appeler load_dotenv() uniquement quand le fichier existe, avec override=False, et à laisser l'environnement réel gagner partout ailleurs. Vous perdez un peu de confort, vous gagnez une règle de priorité que toute l'équipe peut prédire.

    Articles connexes