Python机器学习项目中执行类脚本的推荐存放方式

没有强制统一的行业标准，但两种方案的适用边界非常明确，选型完全看你的项目阶段和脚本用途：

方案1：Entry points 包内注册方案 #

这是生产级、需要对外分发的Python项目的首选方案，PyTorch、Hugging Face 系列库、Scikit-learn 等主流开源ML项目的正式命令行工具全部采用这套实现。

优势 #

• 安装包后命令全局可用，用户不需要记脚本在仓库里的具体路径，直接输入注册好的命令（比如你例子里的execute-script1）就能运行，和系统自带命令行工具的使用体验完全一致
• 彻底避免独立脚本常见的导包报错：脚本属于包内模块，导入核心库的路径完全符合Python包规范，不需要手动修改PYTHONPATH、不需要在脚本开头硬写sys.path.append这类不优雅的兜底逻辑
• 脚本和核心库版本严格绑定，不会出现「拉了新版本核心库，本地旧脚本不兼容」的版本错位问题
• 天然跨平台兼容，不需要额外处理Windows系统下Python脚本路径关联、执行权限类的问题

不足 #

• 哪怕用pip install -e .可编辑模式安装，新增脚本后还是要更新打包配置，对需要频繁改训练逻辑、堆临时实验的快速迭代阶段来说，操作稍显繁琐
• 一次性的临时调试脚本放在包内，会污染正式发布的包结构，增加不必要的发布体积

方案2：根目录独立scripts文件夹方案 #

这是学术研究、算法原型快速迭代阶段项目的常用方案，绝大多数论文附带的代码仓库、Kaggle竞赛类项目都采用这套结构。

优势 #

• 改完代码直接就能跑，不需要做任何打包配置，临时想到什么实验逻辑写完就能执行，灵活性拉满，非常适合高频调参、快速试错的场景
• 临时脚本、废弃的实验代码随便丢进文件夹就行，不需要调整发布配置，管理成本极低

不足 #

• 导包问题是重灾区：脚本在包结构外，直接运行时Python解释器找不到核心库的导入路径，新手十有八九会遇到ModuleNotFoundError，很多人会硬写路径拼接逻辑兜底，可移植性极差
• 分发体验差：其他用户用的时候必须先切到项目根目录，输全脚本的相对路径才能执行，没法全局调用
• 版本管理混乱：很容易出现核心库代码更新了，脚本还是旧版本，运行时出各种难排查的逻辑bug

实际工程推荐做法 #

不用非此即彼二选一，按脚本的用途拆分存放即可：

• 稳定的、面向最终用户的正式执行入口（比如正式训练流水线启动命令、批量推理工具、官方数据集预处理脚本），全部放在包内的scripts目录，通过entry points注册成正式CLI命令
• 临时实验脚本、调试用代码、一次性的数据探查脚本，全部放在根目录的独立scripts（或experiments/examples）文件夹，这部分内容不纳入正式打包范围，仅在开发阶段使用

小技巧：如果用独立文件夹存实验脚本，只要在项目根目录写好基础打包配置，执行一次pip install -e .把核心库以可编辑模式安装到当前环境，就能彻底解决导包报错的问题，不需要额外改路径。

内容的提问来源于stack exchange，提问作者alexmolas