如何在pyproject.toml中指定本地相对依赖？

项目结构如下：

root
  - sample/
    - src/
    - tests/
    - pyproject.toml
  - libs/
    - lol/
      - src/
      - tests/
      - pyproject.toml

想要在sample/pyproject.toml中指定lol作为依赖，尝试以下写法后报错：

dependencies = [ 
   "lol @ file://libs/lol"
]

错误信息：

ValueError: non-local file URIs are not supported on this platform: 'file://libs/lol'

需求：不能用绝对路径，不能使用Poetry等第三方工具，希望找到用相对路径、环境变量或占位符的解决办法。

1. 直接使用相对路径（最简便） #

pip支持无需file://前缀的相对路径依赖声明，直接基于sample目录的相对路径填写即可。修改sample/pyproject.toml：

dependencies = [
    "lol @ ../libs/lol"
]

这里../libs/lol表示从sample目录回到上级（root），再进入libs/lol目录，是符合项目结构的相对路径，pip能正确识别并安装本地依赖。

2. 用环境变量灵活指定路径 #

如果需要更灵活的路径配置，可以分离依赖名和路径：

• 先修改sample/pyproject.toml只保留包名：

dependencies = [
    "lol"
]

• 安装时通过--find-links参数结合环境变量指定依赖位置：

# Linux/macOS 设置环境变量
export LOL_DEP_PATH="../libs/lol"
# Windows cmd 设置环境变量
set LOL_DEP_PATH=..\libs\lol
# Windows PowerShell 设置环境变量
$env:LOL_DEP_PATH = "..\libs\lol"

# 安装sample及其依赖
pip install -e . --find-links=$LOL_DEP_PATH  # Linux/macOS/PowerShell
pip install -e . --find-links=%LOL_DEP_PATH%  # Windows cmd

这种方式适合团队内存在不同目录结构的场景，通过环境变量统一配置路径即可。

3. 结合setuptools的setup.cfg配置（若用setuptools构建） #

如果项目基于setuptools，也可以在sample/setup.cfg中配置依赖：

[options]
install_requires =
    lol @ ../libs/lol

原理和第一种方法一致，pip会自动解析相对路径安装本地包。

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