github/gitignore · Python.gitignore
Python .gitignore 템플릿 해설
Python.gitignore가 __pycache__, 가상환경, 패키징 산출물, 테스트·타입검사 캐시, 비밀 설정을 무시하는 이유와 lib/·lockfile 관련 주의점을 설명합니다.
Python.gitignore는 순수 Python 프로젝트부터 Django·Flask 웹 앱, 데이터 과학, 패키지 배포까지 두루 쓰도록 만든 큰 템플릿이다. 바이트코드 캐시, 가상환경, 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 DB, 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