github/gitignore · Python.gitignore
Python .gitignore 模板详解
说明 Python.gitignore 忽略 __pycache__、虚拟环境、打包产物、测试与类型检查缓存以及机密配置的原因,以及与 lib/、lockfile 相关的注意事项。
Python.gitignore 是一个大型模板,适用于从纯 Python 项目到 Django、Flask Web 应用、数据科学以及包发布的各种场景。它把字节码缓存、虚拟环境、setup.py/构建后端生成的打包目录,以及 pytest、mypy、ruff 等工具的缓存集中在一起。
规则多,也就意味着有些路径会被意外匹配。尤其是它会在任意深度忽略 lib/、build/、dist/、target/ 这类常见名称的目录,因此在与其他语言混合的仓库中,最好先测试一下结果。
逐条规则详解
| 模式 | 忽略什么,为什么忽略 |
|---|---|
__pycache__/*.py[codz]*$py.class*.so | 字节码与扩展模块解释器在 import 时生成的 .pyc 缓存,以及构建 C 扩展得到的共享库。*.py[codz] 是一次匹配 .pyc、.pyo、.pyd、.pyz 的方括号模式。它们都可以从源码重新生成。 |
build/dist/*.egg-info/*.eggwheels/sdist/MANIFEST | 打包产物python -m build 或 setuptools 生成的分发文件和元数据。分发产物应上传到 PyPI 等仓库,而不是放进源码仓库。 |
.venvvenv/env/ENV/__pypackages__/ | 虚拟环境其中写死了解释器路径,移到其他电脑上就无法工作,而且体积很大。依赖应通过 requirements.txt 或 pyproject.toml 加 lockfile 共享。 |
.pytest_cache/.tox/.nox/.coveragehtmlcov/coverage.xml.hypothesis/ | 测试与覆盖率缓存测试运行器和覆盖率工具留下的结果与缓存。每次运行都会变化,只作为 CI 产物处理。 |
.mypy_cache/.pyre/.pytype/.ruff_cache/ | 类型检查与代码检查缓存为加快静态分析而使用的本地缓存,删除后下次运行时会重新生成。 |
local_settings.pydb.sqlite3instance/.webassets-cachecelerybeat-schedule* | 框架本地数据Django 的本地设置和开发用 SQLite 数据库、Flask 的 instance/ 目录、Celery beat 调度文件。每个开发者的内容不同,而且容易包含机密值。 |
.env.envrc.pypirc.streamlit/secrets.toml | 机密信息环境变量文件、direnv 配置、存放 PyPI 上传令牌的 .pypirc、Streamlit 机密配置。一旦提交就会留在历史中,因此从一开始就要排除。 |
.ipynb_checkpointsprofile_default/ipython_config.py/sitedocs/_build/ | 笔记本与其他工具Jupyter 检查点、IPython 配置文件、mkdocs(/site)和 Sphinx(docs/_build/)的构建结果。/site 前面带 /,因此只指仓库根目录下的 site。 |
实践中的注意事项
lib/、lib64/规则会忽略任意深度的lib目录。如果前端代码位于src/lib/,请把规则改为/lib/,或添加!src/lib/。- 模板只在注释中提到
poetry.lock、uv.lock、pdm.lock、Pipfile.lock,并不忽略它们。对于应用程序,通常会提交它们以实现可复现的安装。 - 请记住
.venv末尾没有/,因此同名的文件(例如记录虚拟环境路径的工具配置文件)也会被忽略。 - Jupyter 笔记本的运行结果(输出单元格)无法用 gitignore 拦截。如果要清除输出后再提交,请使用 nbstripout 之类的工具。
原始模板
Python.gitignore
# Byte-compiled / optimized / DLL files__pycache__/*.py[codz]*$py.class# C extensions*.so# Distribution / packaging.Pythonbuild/develop-eggs/dist/downloads/eggs/.eggs/lib/lib64/parts/sdist/var/wheels/share/python-wheels/*.egg-info/.installed.cfg*.eggMANIFEST# PyInstaller# Usually these files are written by a python script from a template# before PyInstaller builds the exe, so as to inject date/other infos into it.*.manifest*.spec# Installer logspip-log.txtpip-delete-this-directory.txt# Unit test / coverage reportshtmlcov/.tox/.nox/.coverage.coverage.*.cachenosetests.xmlcoverage.xml*.cover*.py.cover*.lcov.hypothesis/.pytest_cache/cover/# Translations*.mo*.pot# Django stuff:*.loglocal_settings.pydb.sqlite3db.sqlite3-journal# Flask stuff:instance/.webassets-cache# Scrapy stuff:.scrapy# Sphinx documentationdocs/_build/# PyBuilder.pybuilder/target/# Jupyter Notebook.ipynb_checkpoints# IPythonprofile_default/ipython_config.py# pyenv# For a library or package, you might want to ignore these files since the code is# intended to run in multiple environments; otherwise, check them in:# .python-version# pipenv# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.# However, in case of collaboration, if having platform-specific dependencies or dependencies# having no cross-platform support, pipenv may install dependencies that don't work, or not# install all needed dependencies.# Pipfile.lock# UV# Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.# This is especially recommended for binary packages to ensure reproducibility, and is more# commonly ignored for libraries.# uv.lock# poetry# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.# This is especially recommended for binary packages to ensure reproducibility, and is more# commonly ignored for libraries.# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control# poetry.lock# poetry.toml# pdm# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.# pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.# https://pdm-project.org/en/latest/usage/project/#working-with-version-control# pdm.lock# pdm.toml.pdm-python.pdm-build/# pixi# Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.# pixi.lock# Pixi creates a virtual environment in the .pixi directory, just like venv module creates one# in the .venv directory. It is recommended not to include this directory in version control..pixi/*!.pixi/config.toml# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm__pypackages__/# Celery stuffcelerybeat-schedule*celerybeat.pid# Redis*.rdb*.aof*.pid# RabbitMQmnesia/rabbitmq/rabbitmq-data/# ActiveMQactivemq-data/# SageMath parsed files*.sage.py# Environments.env.envrc.venvenv/venv/ENV/env.bak/venv.bak/# Spyder project settings.spyderproject.spyproject# Rope project settings.ropeproject# mkdocs documentation/site# mypy.mypy_cache/.dmypy.jsondmypy.json# Pyre type checker.pyre/# pytype static type analyzer.pytype/# Cython debug symbolscython_debug/# PyCharm# JetBrains specific template is maintained in a separate JetBrains.gitignore that can# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore# and can be added to the global gitignore or merged into this file. For a more nuclear# option (not recommended) you can uncomment the following to ignore the entire idea folder.# .idea/# Abstra# Abstra is an AI-powered process automation framework.# Ignore directories containing user credentials, local state, and settings.# Learn more at https://abstra.io/docs.abstra/# Visual Studio Code# Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that# can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore# and can be added to the global gitignore or merged into this file. However, if you prefer, you# could uncomment the following to ignore the entire vscode folder# .vscode/# Temporary file for partial code executiontempCodeRunnerFile.py# Ruff stuff:.ruff_cache/# PyPI configuration file.pypirc# Marimomarimo/_static/marimo/_lsp/__marimo__/# Streamlit.streamlit/secrets.toml
模板来源: github/gitignore/Python.gitignore @356fd7b (2026-09-11) · CC0-1.0