Python版本一致时Jupyter仍报No module named 'tqdm'的原因

问题重现 #

在Jupyter Notebook中运行以下训练可视化代码：

import tqdm
generator, gen_optimizer = ipex.optimize(generator, optimizer=gen_optimizer)
from torch.utils.tensorboard import SummaryWriter 
writer = SummaryWriter('./log')

触发如下错误：

---------------------------------------------------------------------------
ModuleNotFoundError                       Traceback (most recent call last)
Cell In[13], line 2
      1 ## optimizaiton with ipex
----> 2 import tqdm
      3 generator, gen_optimizer = ipex.optimize(generator, optimizer=gen_optimizer)
      4 from torch.utils.tensorboard import SummaryWriter 

ModuleNotFoundError: No module named 'tqdm'  

已完成的排查 #

• 通过终端执行pip list确认已安装tqdm 4.65.0
• 检查Jupyter与终端的Python版本，均为3.9.16：
  • Jupyter中执行：

    import platform
    print(platform.python_version())
    >>>3.9.16
    

  • 终端中执行：

    u203216@s001-n054:~$ python
    Python 3.9.16 (main, Jun 15 2023, 02:33:25) 
    [GCC 13.1.0] :: Intel Corporation on linux
    Type "help", "copyright", "credits" or "license" for more information.
    Intel(R) Distribution for Python is brought to you by Intel Corporation.
    >>> import platform
    >>> print(platform.python_version())
    3.9.16
    

原因分析及解决方法 #

1. pip与Jupyter使用的Python环境路径不一致 #

即使版本号相同，不同的Python安装实例（比如系统Python、虚拟环境Python、Intel定制Python）可能共享版本号但属于不同路径，导致终端安装的tqdm不在Jupyter的环境中。

• 验证方式：
  • 在Jupyter单元格中执行：import sys; print(sys.executable)，得到当前内核使用的Python路径
  • 在终端执行：which python（Linux/macOS）或where python（Windows），得到终端Python路径
  • 对比两个路径，若不一致则说明环境不同
• 解决方法：在Jupyter单元格中直接执行!pip install tqdm，将包安装到当前内核对应的环境中

2. Jupyter内核关联环境错误 #

Jupyter的内核可能未关联到安装了tqdm的Python环境，即使Notebook显示的版本号正确，内核实际指向的是另一个同版本但无tqdm的环境。

• 验证方式：在Jupyter单元格中执行!pip list，查看输出中是否包含tqdm
• 解决方法：
  1. 在终端激活目标Python环境
  2. 执行python -m ipykernel install --user --name=自定义内核名，将环境注册为Jupyter内核
  3. 重启Jupyter，在Notebook的内核选择菜单中切换到刚注册的内核

3. 权限问题导致包无法访问 #

如果tqdm是用sudo pip install或其他高权限方式安装的，Jupyter运行的用户可能没有读取该包目录的权限，导致无法导入。

• 解决方法：执行!pip install --user tqdm（Jupyter单元格中）或pip install --user tqdm（终端），将包安装到当前用户的私有目录，确保Jupyter能正常访问

4. Jupyter内核未重新加载 #

若安装tqdm后未重启Jupyter内核，内核可能仍处于缓存状态，无法识别新安装的包。

• 解决方法：点击Jupyter界面的「Kernel」→「Restart Kernel」，重启后再尝试导入tqdm

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