You need to enable JavaScript to run this app. VSCode配置PEP582运行包搜索路径及__pypackages__下ipykernel启动问题
优惠活动
大模型
产品
解决方案
定价
更多

VSCode配置PEP582运行包搜索路径及__pypackages__下ipykernel启动问题

PEP582 规范包管理器(PDM/PyFlow)VSCode 适配配置

基础配置现状

遵循PEP582规范的包管理器(PDM、PyFlow)会将项目依赖统一安装到工作区本地目录{workspace_path}/__pypackages__/下。
目前已在VSCode的settings.json中配置了代码智能识别相关路径,自动补全、行内文档提示功能可正常运行,已添加的配置如下:

{
  ...,
  "python.autoComplete.extraPaths": [
    "__pypackages__/3.7lib"
  ],
  "python.analysis.extraPaths": [
    "__pypackages__/3.7/lib"
  ]
}

小提示:配置中python.autoComplete.extraPaths对应的路径__pypackages__/3.7lib属于笔误,和PDM/PyFlow的默认目录结构不匹配,正确路径应为__pypackages__/3.7/lib,否则部分边界场景下的自动补全可能失效。

现存运行异常

测试用main.py文件内容:

# main.py
#%% jupyter cell
import sys
print(sys.path)
import pandas as pd
print(pd.__version__)
#%% 
print("hello world")

通过两种方式运行该文件时,均触发报错:ModuleNotFoundError: No module named 'pandas'

  1. 使用快捷键ctrl + opt + N直接运行整个文件
  2. 使用快捷键shift + enter调用ipykernel运行Jupyter单元(首次运行时VSCode默认通过pip将ipykernel安装到全局环境,未安装到__pypackages__目录)

通过打印sys.path确认,当前运行时的Python模块搜索路径未包含任何__pypackages__相关目录,实际路径输出为:

['{$HOME}/{workspace}',
 '{$HOME}/.vscode/extensions/ms-toolsai.jupyter-2021.5.745244803/pythonFiles',
 '{$HOME}/.vscode/extensions/ms-toolsai.jupyter-2021.5.745244803/pythonFiles/lib/python',
 '{$HOME}/.pyenv/versions/3.7.10/lib/python37.zip',
 '{$HOME}/.pyenv/versions/3.7.10/lib/python3.7',
 '{$HOME}/.pyenv/versions/3.7.10/lib/python3.7/lib-dynload',
 '',
 '{$HOME}/{workspace}/.venv/lib/python3.7/site-packages',
 '{$HOME}/{workspace}/.venv/lib/python3.7/site-packages/IPython/extensions',
 '{$HOME}/.ipython']

对应配置方案

1. 为Python文件运行流程添加__pypackages__包搜索路径

要解决直接运行文件时找不到本地依赖的问题,核心是在运行时环境中注入__pypackages__的路径,让Python解释器能搜索到对应目录的包,有两种配置方式可选:

  • 方式一:直接在settings.json中配置分平台的终端运行环境变量,将__pypackages__路径加入PYTHONPATH:
    {
      ...,
      "terminal.integrated.env.osx": {
        "PYTHONPATH": "${workspaceFolder}/__pypackages__/3.7/lib"
      },
      "terminal.integrated.env.linux": {
        "PYTHONPATH": "${workspaceFolder}/__pypackages__/3.7/lib"
      },
      "terminal.integrated.env.windows": {
        "PYTHONPATH": "${workspaceFolder}/__pypackages__/3.7/lib"
      },
      "python.envFile": "${workspaceFolder}/.env"
    }
    
  • 方式二:在工作区根目录新建.env文件,写入单行路径配置,无需分平台重复设置:
    PYTHONPATH=./__pypackages__/3.7/lib
    

注意:配置中的Python版本号要和实际__pypackages__下的目录结构完全匹配,例如本地使用Python3.10时,需将路径替换为3.10/lib。

2. 让Jupyter服务使用__pypackages__目录下安装的ipykernel

要实现Jupyter单元运行时正常加载本地依赖、使用本地安装的ipykernel,需要完成两步配置:

  • 首先复用上面的PYTHONPATH配置,Jupyter运行时会自动读取python.envFile定义的环境变量,即可识别__pypackages__目录下安装的pandas等第三方包。
  • 其次注册指向本地ipykernel的专属内核,避免Jupyter默认调用全局安装的ipykernel:
    1. 先通过PDM/PyFlow将ipykernel安装到本地__pypackages__目录,不要使用全局pip安装。
    2. 在工作区终端执行内核注册命令,将本地的ipykernel添加到Jupyter内核列表:
      ${workspace_folder}/__pypackages__/3.7/bin/python -m ipykernel install --user --name pypkgs-py37 --display-name "Python (PEP582 本地包)"
      
    3. 在VSCode的Jupyter内核选择面板中,选中刚注册的「Python (PEP582 本地包)」,运行单元时就会直接加载本地目录下的ipykernel和对应依赖,不再搜索全局路径。
  • 简化配置:如果不想手动注册内核,也可以在settings.json中直接指定VSCode默认使用的Python解释器路径,指向本地__pypackages__下的Python可执行文件:
    {
      ...,
      "python.defaultInterpreterPath": "${workspaceFolder}/__pypackages__/3.7/bin/python"
    }
    

内容的提问来源于stack exchange,提问作者Xaree Lee

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.10.22 13:06:03