安装了 python-dotenv 后出现报错 “ModuleNotFoundError: No module named ‘dotenv’”
一、背景与问题
在开发 Python 应用时，我们常常需要管理环境变量。python-dotenv 是一个流行的库，用于将 .env 文件中的环境变量加载到 os.environ 中。然而，许多开发者在使用过程中会遇到以下错误：
ModuleNotFoundError: No module named 'dotenv'尽管已经通过 pip install python-dotenv 安装了库，但仍然报错。这个错误通常与模块名称、版本兼容性、导入方式或项目结构有关。
二、基本原理
python-dotenv 的核心功能是将 .env 文件中的键值对加载到当前 Python 进程的环境变量中。它的实现依赖于以下机制：
- 模块结构：
python-dotenv的源码中包含dotenv模块，但该模块的导入路径可能因版本不同而变化。 - 动态加载：通过
load_dotenv()函数读取.env文件，并将变量注入os.environ。 - 版本差异：不同版本的
python-dotenv可能在模块命名或导入方式上存在差异。
三、环境准备
1. 安装依赖
确保已安装 python-dotenv：
pip install python-dotenv2. 创建 .env 文件
在项目根目录创建 .env 文件，内容如下：
DEBUG=True
SECRET_KEY=your_secret_key3. 项目结构示例
my_project/
├── .env
├── main.py
├── requirements.txt
└── README.md四、核心实现
1. 正确的导入方式
在 Python 脚本中，需要正确导入 python-dotenv 的模块。注意模块名与包名的区别：
# 正确导入方式（v1.0.0 及以上版本）
from dotenv import load_dotenv# 错误导入方式（可能因版本或路径问题导致报错）
import dotenv # 此处可能报错，需确认模块路径错误原因分析
- 版本差异：早期版本（如 v0.14.0）可能使用
dotenv模块，而新版本改为dotenv模块的子模块。 - 路径问题：若项目结构复杂，可能需要显式指定
.env文件路径。
2. 加载环境变量
import os
from dotenv import load_dotenv
# 加载当前目录下的 .env 文件
load_dotenv()
# 使用环境变量
print(os.getenv("DEBUG")) # 输出: True关键代码解释
load_dotenv()会读取当前目录下的.env文件，若未找到则忽略。os.getenv()用于获取环境变量，若未设置则返回None。
3. 指定 .env 文件路径
from dotenv import load_dotenv
# 指定其他路径的 .env 文件
load_dotenv(".env.prod") # 加载 .env.prod 文件注意事项
- 路径必须相对于当前工作目录，否则会抛出
FileNotFoundError。 - 若未指定路径，默认加载
./.env，但此行为可能因版本不同而变化。
五、完整案例
场景：Flask 应用中使用 python-dotenv
1. 项目结构
flask_app/
├── .env
├── app.py
└── requirements.txt2. requirements.txt
Flask==2.3.2
python-dotenv==1.0.03. app.py
from flask import Flask
from dotenv import load_dotenv
import os
app = Flask(__name__)
# 加载环境变量
load_dotenv()
@app.route("/")
def index():
return f"Debug mode: {os.getenv('DEBUG')} | Secret Key: {os.getenv('SECRET_KEY')}"
if __name__ == "__main__":
app.run(debug=os.getenv("DEBUG") == "True")4. 运行应用
python app.py5. 预期输出
Debug mode: True | Secret Key: your_secret_key6. 错误处理
若 .env 文件不存在，load_dotenv() 会静默忽略，但环境变量会缺失。建议添加验证逻辑：
if not os.getenv("SECRET_KEY"):
raise ValueError("Secret key not found in .env file")六、源码解析
1. python-dotenv 的核心逻辑
查看 python-dotenv 的源码（以 v1.0.0 为例），核心代码位于 dotenv.py：
import os
import dotenv
def load_dotenv(filename=None):
if filename is None:
filename = ".env"
dotenv.load_dotenv(filename)关键点
load_dotenv()会调用dotenv.load_dotenv()，但此函数在旧版本中可能不存在。- 路径处理依赖
os.path模块，需确保路径正确。
2. 版本差异分析
| 版本 | 模块名 | 导入方式 | 路径处理方式 |
|---|---|---|---|
| v0.14.0 | dotenv | import dotenv | 相对路径 |
| v1.0.0+ | dotenv | from dotenv import load_dotenv | 绝对路径或相对路径 |
七、进阶使用
1. 环境变量优先级
python-dotenv 会覆盖系统环境变量，但可以通过 override=False 避免：
load_dotenv(override=False) # 系统变量优先2. 多环境配置
创建多个 .env 文件并按需加载：
# 生产环境
load_dotenv(".env.prod")
# 开发环境
load_dotenv(".env.dev")3. 安全性考虑
敏感信息泄露风险：
.env文件可能被提交到版本控制（如 Git），需在.gitignore中声明：.env .env.* # 匹配所有 .env 文件- 环境变量注入：在生产环境中，建议通过运维工具（如 Docker、Kubernetes）注入环境变量，而非依赖
.env文件。
八、性能与工程实践
1. 性能优化
- 避免重复加载：在应用启动时加载一次，避免重复调用
load_dotenv()。 - 缓存环境变量：使用
os.environ的不可变性，避免频繁修改。
2. 异常处理
try:
load_dotenv()
except Exception as e:
print(f"Failed to load .env: {e}")3. 日志记录
import logging
logging.basicConfig(level=logging.INFO)
def load_dotenv_with_logging(filename=None):
try:
load_dotenv(filename)
logging.info("Successfully loaded .env")
except Exception as e:
logging.error(f"Failed to load .env: {e}")九、常见问题与踩坑
1. 模块名混淆
错误代码：
import dotenv # 错误！可能报错正确方式：
from dotenv import load_dotenv # 正确2. 路径错误
错误场景：
.env文件位于config/目录，但代码中未指定路径。
解决方案：
load_dotenv("config/.env") # 指定完整路径3. 版本兼容性问题
问题描述：
- 使用
python-dotenvv0.14.0 时，load_dotenv()需要dotenv模块。
解决方案：
import dotenv
dotenv.load_dotenv()4. 虚拟环境未激活
错误场景：
- 在全局环境中安装了
python-dotenv，但未激活虚拟环境。
解决方法：
# 激活虚拟环境
source venv/bin/activate十、最佳实践
1. 使用场景
- 开发环境：管理配置、API 密钥、调试标志等。
- 测试环境：隔离测试配置，避免污染生产数据。
- 本地开发：快速切换不同环境配置。
2. 不推荐使用场景
- 生产环境：避免将敏感信息明文存储在
.env文件中。 - 多机部署：推荐通过配置管理工具（如 Ansible、Kubernetes ConfigMap）注入环境变量。
- 跨平台项目：使用
os.environ或系统变量更可靠。
3. 安全建议
- 加密敏感信息：使用
cryptography库对敏感值进行加密。 - 限制访问权限：确保
.env文件不在版本控制中，且权限设置为600。 - 审计日志：记录
.env文件的加载和修改历史。
十一、总结
python-dotenv 是一个强大的工具，但其使用需注意以下几点：
- 模块名与版本兼容性：确保导入方式与版本匹配，避免
ModuleNotFoundError。 - 路径管理：明确
.env文件路径，避免因路径错误导致加载失败。 - 安全实践：避免将敏感信息明文存储，结合加密和权限控制。
- 性能优化：避免重复加载，合理缓存环境变量。
在实际开发中，python-dotenv 适用于开发和测试环境，但在生产环境中应优先使用更安全的配置管理方案。理解其原理和常见陷阱，能帮助开发者更高效地管理环境变量，避免因配置问题导致的开发瓶颈。