使用Python解释器时无法找到已安装模块的问题排查求助

1. 解释器与脚本用的不是同一个Python环境 #

这是最常见的问题。你运行.py文件时调用的Python版本（或虚拟环境），和打开交互式解释器时默认启动的版本可能不一样。比如脚本用的是虚拟环境里的python3.10，但你直接敲python打开的是系统自带的python3.8，两个环境的模块是完全隔离的。

• 验证方式：
  • 在你的脚本开头加两行代码：

    import sys
    print("脚本使用的Python路径：", sys.executable)
    print("脚本的模块搜索路径：", sys.path)
    

    运行脚本后记录输出。
  • 打开交互式解释器，输入同样的代码，对比两者的sys.executable和sys.path是否一致。
• 解决办法：
  • 用脚本对应的Python版本启动解释器，比如脚本用python3.10运行，就敲python3.10打开交互模式。
  • 如果用了虚拟环境，先激活环境再打开解释器。

2. 解释器启动的工作目录和脚本运行时不同 #

如果你的脚本里有修改sys.path的代码（比如手动添加当前目录下的模块文件夹），或者模块是放在脚本所在目录的子文件夹里，而你打开解释器时的工作目录不是脚本所在目录，就会导致找不到模块。

• 验证方式：
  • 在脚本和解释器里分别输入：

    import os
    print("当前工作目录：", os.getcwd())
    

    对比两者的输出。
• 解决办法：
  • 启动解释器前先切换到脚本所在目录，或者在解释器里用os.chdir("你的脚本所在绝对路径")切换目录。
  • 把模块安装到全局的site-packages或者虚拟环境的依赖目录，不要依赖本地工作目录。

3. 解释器启动时缺失关键环境变量 #

脚本运行时可能加载了PYTHONPATH环境变量（这个变量会添加到Python的模块搜索路径），但交互式解释器启动时没读到这个变量，导致搜索路径里没有模块所在的目录。

• 验证方式：
  • 在脚本和解释器里分别输入：

    import os
    print("PYTHONPATH:", os.environ.get("PYTHONPATH"))
    

    对比输出内容。
• 解决办法：
  • 启动解释器前先设置PYTHONPATH，比如终端里运行export PYTHONPATH="/你的模块所在目录:$PYTHONPATH"，再打开解释器。
  • 临时在解释器里添加路径：import sys; sys.path.append("/你的模块所在绝对路径")。

4. 模块安装路径与解释器的权限/路径不匹配 #

即使运行脚本没问题，也可能出现模块安装到了用户私有目录（比如~/.local/lib/pythonX.Y/site-packages），但你打开的解释器是系统级Python，无法访问用户目录的模块；或者反过来，脚本用的是用户级Python，解释器用的是系统级。

• 验证方式：
  • 在脚本和解释器里分别输入：

    import site
    print("site-packages路径：", site.getsitepackages())
    

    查看输出里是否包含你的模块所在的目录。
• 解决办法：
  • 用对应环境的pip安装模块：虚拟环境里直接用pip install，系统级用sudo pip install，用户级用pip install --user。

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