如何通过pyproject.toml(PEP517)配置Python包安装至指定目录

方案一：通过构建配置直接指定分发后的包名 #

核心逻辑：Python包安装到site-packages的目录名由分发包中的包名决定，而非直接配置安装路径。通过调整构建工具的包映射配置，可将源码中的foo目录映射为分发后的foo2目录，从而实现安装到site-packages/foo2。

setuptools实现 #

1. 采用src布局的项目结构：

foo-project/
├── src/
│   └── foo/
│       ├── __init__.py
│       └── your_module.py
└── pyproject.toml

2. 配置pyproject.toml：

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

[project]
name = "foo"
version = "0.1.0"

[tool.setuptools]
# 指定分发后的包名为foo2
packages = ["foo2"]
# 将源码目录src/foo映射到分发包的foo2
package_dir = {"foo2" = "src/foo"}

3. 构建并安装：

python -m build --wheel
pip install dist/foo-0.1.0-py3-none-any.whl

安装后，site-packages下会出现foo2目录，包含原src/foo中的代码。

其他后端实现 #

• flit-core：
  在pyproject.toml中直接配置包映射：

  [build-system]
  requires = ["flit-core>=3.8"]
  build-backend = "flit_core.buildapi"
  
  [project]
  name = "foo"
  version = "0.1.0"
  packages = [{"foo2" = "src/foo"}]
  

• hatchling：
  通过package-map配置映射：

  [build-system]
  requires = ["hatchling"]
  build-backend = "hatchling.build"
  
  [project]
  name = "foo"
  version = "0.1.0"
  
  [tool.hatch.build.targets.wheel]
  packages = ["src/foo"]
  package-map = {"foo" = "foo2"}
  

• poetry：
  在packages配置中添加重命名规则：

  [tool.poetry]
  name = "foo"
  version = "0.1.0"
  packages = [
    { include = "foo", from = "src", rename = "foo2" },
  ]
  
  [build-system]
  requires = ["poetry-core>=1.0.0"]
  build-backend = "poetry.core.masonry.api"
  

方案二：默认构建foo包，安装时修改目录名 #

如果希望保留原始包的构建配置，仅在安装阶段修改目标目录，可通过修改wheel包的结构实现：

1. 构建原始wheel包：

python -m build --wheel

生成dist/foo-0.1.0-py3-none-any.whl。

2. 修改wheel中的包目录名：

# 解压wheel到临时目录
unzip dist/foo-0.1.0-py3-none-any.whl -d temp_wheel
# 重命名包目录
mv temp_wheel/foo temp_wheel/foo2
# 重新打包wheel
cd temp_wheel && zip -r ../dist/foo2-0.1.0-py3-none-any.whl *

3. 安装修改后的wheel：

pip install dist/foo2-0.1.0-py3-none-any.whl

此方法无需修改项目配置，仅在安装前调整wheel结构，适合临时需求。

注意：pip本身没有直接修改安装目录下包名的内置参数，上述是最可靠的临时解决方案。

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