VSCode无法远程attach调试Docker容器内Jupyter Notebook问题求助

• 你使用的ptvsd是微软已经停止维护的老旧调试组件，对Python 3.9+以及Jupyter的多进程模型兼容性极差，是故障的核心诱因之一。
• Jupyter采用多进程架构：你启动的jupyter lab主进程仅负责网页服务、任务调度，实际运行.ipynb代码的是独立启动的内核子进程。你直接把调试器绑定在jupyter主进程上，第一次attach后主进程就会直接放行启动，调试器不会自动注入后续启动的内核子进程，自然无法调试notebook内的代码，表现出来就是挂载中断、调试不生效。
• ptvsd的--multiprocess参数对Jupyter内核的fork逻辑支持不完善，无法自动跟踪子进程。

步骤1：替换ptvsd为debugpy #

debugpy是微软当前官方维护的Python调试后端，兼容性远高于ptvsd，在你的Dockerfile中调整安装逻辑：

RUN pip uninstall -y ptvsd && pip install debugpy

步骤2：选择调试注入方式 #

方式A：固定内核配置（适合高频调试场景） #

给Jupyter Python内核配置自动注入debugpy，每次使用该内核启动的notebook都会自动开启调试监听：

1. 执行命令jupyter kernelspec list找到Python3内核的配置目录，默认路径为/opt/conda/share/jupyter/kernels/python3/
2. 复制该目录重命名为python3-debug，修改目录下的kernel.json文件：

{
 "argv": [
  "python",
  "-m", "debugpy",
  "--listen", "0.0.0.0:49155",
  "--wait-for-client",
  "-m", "ipykernel_launcher",
  "-f", "{connection_file}"
 ],
 "display_name": "Python 3 (Debug)",
 "language": "python"
}

该方式会保留默认内核，调试时手动切换内核即可，不影响普通使用。

方式B：单notebook手动注入（适合偶尔调试场景） #

无需修改全局配置，在需要调试的notebook第一个代码块中添加以下代码即可启动调试监听：

import debugpy
# 避免重复启动报错
if not debugpy.is_attached():
    debugpy.listen(("0.0.0.0", 49155))
    print("等待调试器挂载...")
    debugpy.wait_for_client()

步骤3：调整启动配置 #

1. 移除原Dockerfile中给jupyter lab加的ptvsd启动参数，改用原生启动命令：

CMD ["jupyter", "lab", "--ip", "0.0.0.0", "--allow-root"]

2. 调整VSCode的launch.json配置，添加justMyCode参数避免调试跳转到无关库代码：

{
    "name": "Python: Remote Attach",
    "type": "python",
    "request": "attach",
    "connect": {
        "host": "127.0.0.1",
        "port": 49155
    },
    "pathMappings": [
        {
            "localRoot": "${workspaceFolder}/notebooks",
            "remoteRoot": "/home/jovyan"
        }
    ],
    "justMyCode": false
}

docker compose的端口映射配置无需修改。

调试流程 #

1. 启动容器后打开Jupyter Lab网页，打开需要调试的notebook，选择Python 3 (Debug)内核（使用方式B的话直接用默认内核，运行第一块代码即可）
2. 内核等待调试挂载时，在VSCode启动调试会话
3. 挂载成功后即可在notebook代码块打断点，运行代码时会正常触发调试逻辑。

注意：如果需要同时调试多个notebook内核，不要在内核配置里写死端口，改用方式B手动指定不同端口即可避免冲突。

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