Poetry本地自定义插件无法识别，poetry install版本解析失败求助

环境版本 #

Poetry (version 2.1.1)
Python 3.13.2
pip 25.0.1 from <correct path to the pip location in venv>

插件项目配置 #

插件mycoolplugin的pyproject.toml核心配置：

[project]
name = "mycoolplugin"
version = "1.0.0"
...
[tool.poetry.plugins."poetry.application.plugin"]
mycoolplugin = "mycoolplugin:CoolPlugin"

该插件可正常构建wheel包，自身项目及pytest测试运行正常。

目标项目配置 #

需要使用插件的项目中，pyproject.toml配置：

[tool.poetry.requires-plugins]
mycoolplugin = ">=1.0.0"

[[tool.poetry.source]]
name = "company-pypi"
url = "https://artifactory.company.com/api/pypi/pypi.python.org/simple"
priority = "primary"

操作与错误 #

插件未发布到内部PyPI源，手动操作步骤：

1. 创建并激活目标项目虚拟环境
2. 执行pip install ../mycoolplugin/dist/mycoolplugin-1.0.0-py3-none-any.whl，pip list显示插件已安装（版本1.0.0）

但执行poetry install报错：

poetry install
Removing the project's plugin cache because it is outdated
Ensuring that the Poetry plugins required by the project are available...
The following Poetry plugins are required by the project but are not installed in Poetry's environment:
  - mycoolwplugin (>=1.0.0)
Installing Poetry plugins only for the current project...
Updating dependencies
Resolving dependencies...

Because poetry-project-instance depends on mycoolplugin (>=1.0.0) which doesn't match any versions, version solving failed.

执行poetry add mycoolplugin同样失败：

poetry add mycoolplugin

Could not find a matching version of package mycoolplugin

此前功能正常，清理构建文件后出现该问题。

核心原因 #

1. Poetry插件依赖与pip环境分离：Poetry对插件的管理独立于项目虚拟环境的pip包。当配置[tool.poetry.requires-plugins]时，Poetry会优先从配置的PyPI源（此处为公司内部源）查找插件，不会读取当前虚拟环境中pip已安装的包。清理构建文件后，之前可能存在的本地插件缓存被清除，导致Poetry无法找到插件。
2. 拼写错误风险：错误信息中出现了mycoolwplugin（多了一个w），需检查[tool.poetry.requires-plugins]中的包名是否与插件name完全一致，拼写错误会直接导致Poetry无法匹配。

解决方法 #

方法一：直接指定本地插件路径 #

修改目标项目的pyproject.toml，将插件依赖指向本地项目或wheel包路径：

[tool.poetry.requires-plugins]
mycoolplugin = { path = "../mycoolplugin" }
# 或者指向wheel文件
# mycoolplugin = { path = "../mycoolplugin/dist/mycoolplugin-1.0.0-py3-none-any.whl" }

这样Poetry会直接从本地读取插件，无需依赖PyPI源。

方法二：将插件安装到Poetry自身环境 #

Poetry有独立的运行环境，需将插件安装到该环境中：

• 如果Poetry是通过pipx安装的，执行：

  pipx inject poetry ../mycoolplugin/dist/mycoolplugin-1.0.0-py3-none-any.whl
  

• 如果Poetry是通过pip安装的，找到Poetry对应的Python环境，执行：

  <path-to-poetry-python> -m pip install ../mycoolplugin/dist/mycoolplugin-1.0.0-py3-none-any.whl
  

  可通过which poetry定位Poetry的安装路径，进而找到对应的Python解释器。

方法三：临时跳过插件检查（仅测试用） #

如果只是临时测试项目功能，可执行：

poetry install --no-plugins

此方法会跳过插件依赖检查，不推荐正式环境使用。

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