pytest.ini必须放在项目根目录(即运行pytest命令时的当前工作目录)才生效,若存在更优先的pyproject.toml(含[tool.pytest.ini_options]),则pytest.ini会被完全忽略。

pytest.ini 是有效的,但必须放在项目根目录且不能被其他配置文件覆盖。
pytest.ini 文件必须放在哪里才生效
pytest 启动时会向上查找最近的配置文件,顺序是:pytest.ini → pyproject.toml → setup.cfg → tox.ini。只要找到第一个就停止,pytest.ini 只有在没有更优先配置文件时才起作用。
- 把
pytest.ini放在项目最外层目录(即运行pytest命令时的当前工作目录) - 如果项目里已有
pyproject.toml且含[tool.pytest.ini_options],pytest.ini会被完全忽略 - 执行
pytest tests/时,当前目录不是项目根目录,也会导致pytest.ini不加载
常用参数写法与易错点
ini 文件不支持嵌套或复杂结构,所有键值都扁平写在 [tool:pytest] 下,等号右边不能有空格,布尔值用 true/false(小写)。
-
addopts = -v --tb=short -x:多个参数用空格分隔,不要加引号;-v和--tb=short之间不能换行 -
testpaths = tests:指定默认搜索路径,多个路径用空格分隔,如tests unit/integration -
python_files = test_*.py *_test.py:匹配文件名模式,注意通配符语法和空格分隔 -
filterwarnings = ignore::DeprecationWarning:冒号分隔四段,顺序不能错,漏掉任意一段会导致警告过滤失效
为什么改了 pytest.ini 却没生效
最常见原因是 pytest 找到了别的配置源,或者命令行参数覆盖了 ini 设置。
- 运行
pytest -v时,命令行上的-v会覆盖pytest.ini中的addopts里定义的-v,但不会覆盖testpaths这类非冲突参数 - 用
pytest --help查看 “configfile” 行,确认实际加载的是哪个文件 - 执行
pytest --show-config能打印所有最终生效的配置项,比肉眼检查更可靠 - Windows 下注意换行符是
CRLF,某些编辑器保存时可能插入 BOM,导致解析失败(表现为静默失效)
ini 文件没法做条件判断、变量插值或动态逻辑,复杂场景建议直接迁移到 pyproject.toml —— 它支持更多类型、更清晰的结构,而且现在是 pytest 官方推荐格式。
Python免费学习笔记(深入):立即使用
在学习笔记中,你将探索 Python 的核心概念和高级技巧!











