Windows下运行pdoc出现No Modules found matching spec的解决方法

我在Windows命令行中尝试运行pdoc官方文档中的简单演示脚本，使用Python 3.11.4版本与virtualenv环境，且已将PYTHONPATH配置至目标文件夹。演示代码如下：

"""
A small `pdoc` example.
"""

class Dog:
    """ (dog) """
    name: str
    """The name of our dog."""
    friends: list["Dog"]
    """The friends of our dog."""

    def __init__(self, name: str):
        """Make a Dog without any friends (yet)."""
        self.name = name
        self.friends = []

    def bark(self, loud: bool = True):
        """*woof*"""

执行命令pdoc .\demo.py后，出现以下错误信息：

Warn: pdoc cannot load 'pdoc' because a module with the same name is already imported in pdoc's Python process. pdoc will document the loaded module from C:\Pythons\virtenvs\glogger11.4\Lib\site-packages\pdoc\__init__.py instead.
Warn: Cannot find spec for pdoc.demo (from .\demo.py):
Traceback (most recent call last):
  File "C:\Pythons\virtenvs\glogger11.4\Lib\site-packages\pdoc\extract.py", line 62, in walk_specs
    raise ModuleNotFoundError(modname)
ModuleNotFoundError: pdoc.demo
 (C:\Pythons\virtenvs\glogger11.4\Lib\site-packages\pdoc\web.py:105)
Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "C:\Pythons\virtenvs\glogger11.4\Scripts\pdoc.exe\__main__.py", line 7, in <module>
  File "C:\Pythons\virtenvs\glogger11.4\Lib\site-packages\pdoc\__main__.py", line 207, in cli
    httpd = pdoc.web.DocServer((opts.host, opts.port or 8080), opts.modules)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Pythons\virtenvs\glogger11.4\Lib\site-packages\pdoc\web.py", line 105, in __init__
    module_names = extract.walk_specs(specs)
                   ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Pythons\virtenvs\glogger11.4\Lib\site-packages\pdoc\extract.py", line 85, in walk_specs
    raise ValueError(
ValueError: No modules found matching spec: .\demo.py

方法1：用模块名替代路径调用 #

pdoc优先识别模块名而非文件路径，确保demo.py所在目录已在PYTHONPATH中，直接执行：

pdoc demo

此方法能避免Windows路径格式导致的解析误判。

方法2：确认PYTHONPATH配置有效性 #

先检查当前PYTHONPATH是否包含demo.py所在目录：

echo %PYTHONPATH%

若未包含，临时添加（仅当前命令行会话生效）：

set PYTHONPATH=你的demo.py所在目录路径;%PYTHONPATH%

之后再执行pdoc demo。

方法3：切换到脚本目录执行 #

若不想配置PYTHONPATH，直接进入demo.py所在文件夹，执行：

pdoc demo.py

注意不要加.\前缀，避免路径解析问题。

额外提示 #

• 错误中pdoc.demo找不到的问题，是因为.\demo.py的写法让pdoc误将脚本识别为pdoc包的子模块，改用模块名或直接文件名即可解决。
• 若上述方法无效，可尝试绝对路径调用：

pdoc "C:\你的完整路径\demo.py"

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