【python】一般python项目的目录结构

【Python】一般 Python 项目的目录结构

Python 项目没有官方强制规定的目录结构，但社区在长期实践中形成了一些被广泛接受的惯例。不同的项目类型（命令行工具、Web 应用、数据科学项目、库/package、AI 项目等）会有一些差异。

下面列出几种最常见、最推荐的目录结构，以及它们适用的场景。

1. 最经典、最通用的结构（适合大多数中大型项目）

project_name/
├── src/                    # 源代码主目录（推荐把包放在 src 下）
│   └── project_name/       # 实际的 Python 包（可被 import 的部分）
│       ├── __init__.py
│       ├── module1.py
│       ├── module2/
│       │   ├── __init__.py
│       │   └── submodule.py
│       └── core/
│           ├── __init__.py
│           └── utils.py
├── tests/                  # 单元测试、集成测试
│   ├── __init__.py
│   ├── test_module1.py
│   └── test_core/
│       └── test_utils.py
├── docs/                   # 文档（Sphinx、mkdocs 等）
│   ├── conf.py
│   └── index.rst / index.md
├── scripts/                # 一些一次性脚本、管理脚本、运维脚本
│   └── deploy.py
├── notebooks/              # Jupyter notebooks（可选，数据分析/实验用）
├── config/                 # 配置文件（yaml、toml、ini 等）
│   ├── dev.yaml
│   ├── prod.yaml
│   └── default.yaml
├── .github/                # GitHub Actions、issue 模板等
│   └── workflows/
├── data/                   # 数据文件（git 不提交，或只放 sample）
│   └── sample/
├── requirements/           # 依赖文件（现代推荐）
│   ├── base.txt
│   ├── dev.txt
│   └── prod.txt
├── pyproject.toml          # 现代 Python 项目元数据 + 构建配置（强烈推荐）
├── README.md
├── LICENSE
├── .gitignore
├── .pre-commit-config.yaml  # 可选：代码格式化、lint 等钩子
└── setup.cfg / setup.py    # 如果还在用旧式打包（逐渐被 pyproject.toml 取代）

这种结构的核心思想：
把可安装的包（library code）放在 src/project_name/ 下，避免在开发时和打包时路径问题。

---

2. 极简结构（适合小型脚本、工具、个人项目）

mytool/
├── mytool.py             # 主程序文件
├── utils.py              # 辅助函数
├── config.yaml           # 配置文件
├── tests/
│   └── test_mytool.py
├── README.md
├── requirements.txt
└── .gitignore

适合：命令行小工具、学习项目、快速原型。

---

3. Web 项目（FastAPI / Flask / Django）

FastAPI 项目（现代推荐风格）

myapi/
├── app/                     # 应用核心代码
│   ├── __init__.py
│   ├── main.py             # FastAPI app 入口
│   ├── api/                # 接口路由
│   │   ├── __init__.py
│   │   └── v1/
│   │       └── endpoints/
│   ├── core/               # 配置、依赖、工具
│   ├── models/             # Pydantic 模型 / ORM 模型
│   ├── schemas/            # 请求/响应 schema
│   ├── services/           # 业务逻辑层
│   └── database/
├── tests/
├── alembic/                # 数据库迁移（如果使用 SQLAlchemy）
├── .env
├── pyproject.toml
├── README.md
└── requirements/
    ├── base.txt
    └── dev.txt

Django 项目（官方推荐风格）

myproject/
├── manage.py
├── myproject/           # 项目配置文件
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── myapp/               # 业务应用（可以有多个）
│   ├── migrations/
│   ├── __init__.py
│   ├── admin.py
│   ├── apps.py
│   ├── models.py
│   ├── tests.py
│   └── views.py
├── static/
├── templates/
├── media/
└── requirements.txt

---

4. 数据科学 / 机器学习项目常见结构

ml-project/
├── data/                   # 数据（通常不提交，或只提交 sample）
│   ├── raw/
│   ├── processed/
│   └── external/
├── notebooks/              # 探索性分析、实验
│   ├── 01-eda.ipynb
│   └── 02-modeling.ipynb
├── src/                    # 可复用的代码（核心）
│   ├── data/
│   │   └── make_dataset.py
│   ├── features/
│   │   └── build_features.py
│   ├── models/
│   │   └── train_model.py
│   └── visualization/
├── models/                 # 训练好的模型文件（.pkl, .h5, .pt 等）
├── reports/                # 报告、图表
├── requirements.txt
├── pyproject.toml
└── README.md

推荐参考：Cookiecutter Data Science 项目模板

---

5. 现代 Python 项目推荐文件（2025–2026）

这些文件几乎是标配：

• pyproject.toml → 项目元数据、构建配置、依赖（取代 setup.py）
• README.md → 项目说明、使用方法
• .gitignore → 推荐 Python.gitignore 模板
• requirements.txt 或 pyproject.toml + uv/pdm/poetry
• LICENSE → 开源项目必须
• .pre-commit-config.yaml → 代码规范（black、isort、ruff 等）
• .github/workflows/ci.yml → GitHub Actions 自动化测试

推荐现代依赖管理工具（取代 requirements.txt）：

• uv（最快，2025-2026 最火）
• pdm
• poetry
• hatch

---

快速选择参考表

项目类型	推荐结构风格	依赖管理工具推荐	是否用 src/ 布局
小脚本/工具	极简结构	uv / pip	否
中大型库/package	src/ 布局	uv / pdm / poetry	是
FastAPI/Flask Web	app/ 模块化	uv / pdm	是
Django 项目	Django 官方结构	pip / poetry	否
数据科学/ML 项目	Cookiecutter Data Science	uv / conda	是
个人学习/实验	随意 / 极简	uv	随意

一句话总结：

现代 Python 项目最推荐的结构是：用 src/ 布局 + pyproject.toml + uv/pdm/poetry 管理依赖。

如果你有具体项目类型（比如 FastAPI、爬虫、GUI、小工具、AI 训练项目等），可以告诉我，我可以给你更精确的目录结构建议和初始化命令。