本文档介绍了 GitHub gitignore 仓库中包含的 Python 特定的 gitignore 模式。它解释了在 Python 项目中通常应排除在版本控制之外的文件和目录，以及为什么。有关与语言无关的 gitignore 模式的信息，请参阅 gitignore 模板概述。有关 Python 特定 IDE 设置的信息，请参阅 JetBrains IDE（针对 PyCharm）或 Visual Studio 和 .NET（针对 PTVS）。
Python gitignore 模板提供了一套全面的模式，旨在将 Python 特定的生成文件、临时数据、构建产物和特定于环境的配置排除在版本控制之外。这有助于维护干净的仓库，防止团队成员之间的环境冲突，并避免不必要的仓库过大。
Python 开发会生成各种不应纳入版本控制的文件。这些文件可分为几类：
Python 在脚本执行时会自动生成字节码文件，以提高后续运行的性能。这些文件特定于平台，不应提交。
__pycache__/
*.py[cod]
*$py.class
*.so
__pycache__/ 目录包含 Python 3.x 创建的字节码文件。*.py[cod] 匹配 .pyc、.pyo 和 .pyd 字节码文件。*$py.class 是 Jython 生成的编译文件。*.so 文件是为特定平台编译的 C 扩展模块。Python 项目在准备部署或发布到 PyPI 等包仓库时，通常会生成分发文件。这些构建产物应被排除。
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST
本节涵盖了构建分发包时由 setuptools、pip 和其他打包工具创建的目录和文件。
使用 PyInstaller 创建独立可执行文件时，会生成几个不应包含在版本控制中的文件。
*.manifest
*.spec
这些文件是在创建独立可执行文件的构建过程中由 PyInstaller 生成的。
Python 项目通常使用各种测试框架和代码覆盖率工具，这些工具会生成报告和临时文件。
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/
cover/
这些模式会排除由 pytest、nose、coverage.py、tox、nox 和 hypothesis 等测试工具生成的文件。
Python 项目通常使用虚拟环境来隔离依赖项。这些应被排除在版本控制之外。
.env
.venv
env/
venv/
ENV/
env.bak/
venv.bak/
本节还包括了 pipenv、poetry、pdm 和 UV 等各种依赖项管理工具的模式。
#Pipfile.lock
#uv.lock
#poetry.lock
#pdm.lock
.pdm.toml
.pdm-python
.pdm-build/
__pypackages__/
请注意，有些锁文件被注释掉了，因为有时建议将其包含在版本控制中以实现可重现性。
来源：Python.gitignore85-138 Python.gitignore95-122
各种 Python 框架会生成应被排除的文件。
# Django stuff:
*.log
local_settings.py
db.sqlite3
db.sqlite3-journal
# Flask stuff:
instance/
.webassets-cache
# Scrapy stuff:
.scrapy
# Celery stuff
celerybeat-schedule
celerybeat.pid
这些模式会排除流行 Python 框架的数据库文件、本地设置、缓存和运行时文件。
文档生成器、IDE 和其他 Python 工具会创建应被排除的文件。
# Sphinx documentation
docs/_build/
# Jupyter Notebook
.ipynb_checkpoints
# IPython
profile_default/
ipython_config.py
# Type checkers
.mypy_cache/
.dmypy.json
dmypy.json
.pyre/
.pytype/
# Linters
.ruff_cache/
下图说明了 Python 开发中不同阶段生成的文件应如何从版本控制中排除。
Python 开发工作流程和生成的文件
Python 有几种包管理工具，每种工具都有应从版本控制中排除的特定文件。
Python 包管理器和相关 Gitignore 模式
Python 的编译过程会创建几种应从版本控制中排除的文件类型。
| 文件扩展名 | 描述 | 排除原因 |
|---|---|---|
.pyc | 已编译的 Python 文件（Python 2.x 风格） | 特定于平台，自动生成 |
.pyo | 优化的已编译 Python 文件 | 特定于平台，自动生成 |
.pyd | Python DLL 文件（Windows） | 特定于平台的二进制文件 |
__pycache__/ | 包含字节码文件的目录（Python 3.x） | 特定于平台和版本，自动重新生成 |
*.so | 共享对象文件（C 扩展） | 特定于平台的二进制文件 |
*$py.class | Jython 编译文件 | 特定于平台，自动生成 |
Python 项目经常使用可能包含敏感信息的环境变量和配置文件。
| 文件/目录 | 目的 | 排除理由 |
|---|---|---|
.env | 环境变量 | 包含敏感数据（API 密钥、密码） |
.venv/、env/、venv/ | 虚拟环境目录 | 庞大、特定于机器、易于重新创建 |
local_settings.py | Django 本地设置 | 包含本地开发的敏感配置 |
.python-version | pyenv 配置 | 特定于环境，默认注释 |
.pypirc | PyPI 配置 | 包含身份验证凭据 |
来源：Python.gitignore130-138 Python.gitignore173-174
Python 开发者使用各种工具生成应被排除的文件。
| 工具类别 | 生成的代码 | 目的 |
|---|---|---|
| 测试 | .pytest_cache/、.tox/、.nox/、.coverage | 测试执行产物 |
| 文档 | docs/_build/、*.mo、*.pot | 生成的文档和翻译文件 |
| 集成开发环境 (IDE) | .spyderproject、.spyproject、.ropeproject | IDE 特定项目文件 |
| 类型检查 | .mypy_cache/、.pyre/、.pytype/ | 类型检查器缓存文件 |
| 代码 Linting | .ruff_cache/ | Ruff linter 缓存 |
| Notebooks | .ipynb_checkpoints | Jupyter Notebook 检查点 |
Python Web 框架会生成应从版本控制中排除的特定文件。
| 框架 | 被忽略的文件/目录 | 目的 |
|---|---|---|
| Django | db.sqlite3、db.sqlite3-journal、local_settings.py | 数据库文件和本地配置 |
| Flask | instance/、.webassets-cache | 实例特定配置和资源编译 |
| Scrapy | .scrapy | Scrapy 缓存和运行时文件 |
| Celery | celerybeat-schedule、celerybeat.pid | 任务调度器状态文件 |
来源：Python.gitignore58-69 Python.gitignore123-126
在构建用于分发的 Python 包时，会创建几个应被排除的文件和目录。
| 文件/目录 | 目的 | 创建者 |
|---|---|---|
dist/ | 包含已构建的分发包 | setuptools, build |
build/ | 临时构建目录 | setuptools, build |
*.egg-info/ | 已安装包的元数据 | setuptools |
*.egg | Egg 格式分发包 | setuptools (旧版) |
MANIFEST | 源分发包的文件列表 | setuptools |
wheels/ | 已构建的 wheel 包 | wheel |
.gitignore 包含在项目中，以防止意外提交生成的文件。如果您将 Python 与特定技术一起使用，请考虑将此模板与以下内容结合使用：