Sphinx使用furo主题报错：未找到furo主题，求解决方案

问题分析与解决 #

你的核心问题是当前终端调用的sphinx-build和你通过pip安装的Sphinx、furo不在同一个Python环境，导致系统找不到已安装的furo主题。以下是具体排查和解决步骤：

1. 验证环境一致性 #

• 先查pip对应的Python路径：
  Linux/macOS运行：which pip
  Windows运行：where pip
• 用这个Python检查Sphinx版本：python -m sphinx --version（把python换成上面查到的完整路径，比如/home/user/.local/bin/python），应该显示8.0.2；同时运行pip list | grep furo确认furo已安装。
• 再查当前sphinx-build的路径：which sphinx-build（Linux/macOS）或where sphinx-build（Windows），如果和pip的路径不一致，说明调用的是其他环境的旧版本Sphinx。

2. 解决方法（选一个即可） #

• 方法一：直接用Python模块调用sphinx-build
  跳过系统路径的sphinx-build，直接用安装了Sphinx8.0.2的Python执行：

  python -m sphinx.build 你的源码目录 你的构建目录
  

  比如你的源码在docs/source，要构建到docs/build/html，就运行：

  python -m sphinx.build docs/source docs/build/html
  

• 方法二：激活对应的虚拟环境
  如果你用了虚拟环境（比如venv、conda），先激活环境：

  • Linux/macOS：source 你的虚拟环境目录/bin/activate
  • Windows：你的虚拟环境目录\Scripts\activate
    激活后再运行sphinx-build --version，应该显示8.0.2，此时再构建文档就能找到furo主题。

• 方法三：调整环境变量优先级
  Linux/macOS可以把pip安装的工具目录加到PATH最前面，让系统优先用你安装的版本：

  export PATH=~/.local/bin:$PATH
  

  运行后重启终端，再查sphinx-build --version，确认版本为8.0.2后再构建。

额外注意 #

furo主题不需要加到conf.py的extensions列表里，只需要保留html_theme = 'furo'这一行配置即可，之前添加的'furo'可以从extensions里删掉，避免冗余配置。

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