如何通过pyproject.toml将Python脚本配置为命令行可执行文件？

当前配置的问题 #

1. [project.scripts]格式错误：该字段要求模块路径:可调用函数的格式，而非目录:脚本文件的写法，你的"bin:Script1.py"无法被setuptools正确解析。
2. [tool.setuptools.packages.find]配置不合理：include = ["src", "bin"]不是有效的包匹配模式，且bin目录默认不是Python包（缺少__init__.py），setuptools无法识别其中的脚本作为可导入模块。

方案一：使用Console Scripts（推荐，符合Python包规范） #

这种方式将脚本逻辑封装为可调用函数，便于后续维护和测试：

1. 修改脚本文件：在bin/script1.py和bin/script2.py中添加入口函数，保留原有执行逻辑：

# bin/script1.py
def main():
    # 原脚本的所有执行逻辑放在这里
    print("Script1 运行中...")

if __name__ == "__main__":
    main()

2. 将bin目录转为Python包：在bin目录下创建空的__init__.py文件，让setuptools能识别该目录下的模块。

3. 更新pyproject.toml配置：

[build-system]
build-backend = "setuptools.build_meta"
requires = [
  "setuptools",
]

# 补充必填的项目基础配置
[project]
name = "your-package-name"
version = "0.1.0"

[project.scripts]
Script1 = "bin.script1:main"
Script2 = "bin.script2:main"

[tool.setuptools.packages.find]
where = ["src", "bin"]
include = [
    "src.*",
    "bin.*"
]

方案二：直接指定脚本文件（无需修改脚本内容） #

如果不想调整现有脚本结构，可使用tool.setuptools.scripts直接指定脚本路径，setuptools会自动处理可执行权限和路径映射：

[build-system]
build-backend = "setuptools.build_meta"
requires = [
  "setuptools",
]

[project]
name = "your-package-name"
version = "0.1.0"

# 替换原[project.scripts]，直接指定脚本文件路径
[tool.setuptools.scripts]
scripts = ["bin/script1.py", "bin/script2.py"]

# 仅扫描src目录下的包即可
[tool.setuptools.packages.find]
where = ["src"]
include = [
    "src.*"
]

验证安装 #

配置完成后，执行本地开发安装测试：

pip install -e .

安装完成后，直接在终端输入Script1或Script2即可运行对应的脚本。

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