Jupyter故障排查：卸载PyZMQ后无法安装19.0.2版本如何解决

故障触发前提 #

默认安装的PyZMQ 22.3.0存在已知兼容问题，会导致Jupyter内核连接失败、运行中断；卸载该版本后直接安装19.0.2版本时，大概率因编译依赖、版本适配问题安装失败。

安装失败核心诱因 #

• 未指定预编译包参数，pip拉取源码包本地编译，系统缺少C编译环境直接报错
• 旧版本PyZMQ卸载不彻底，残留文件引发版本锁冲突
• Python版本与pyzmq 19.0.2存在兼容上限：pyzmq 19.0.2最高支持Python 3.9，3.10及以上版本无法正常安装该版本

可直接落地的操作步骤 #

1. 彻底清理环境残留
   强制执行卸载命令，重复执行2次确保无残留版本，同时清空pip缓存避免拉到损坏的安装包：

   pip uninstall -y pyzmq
   pip cache purge
   

2. 按自身Python版本选择适配的安装命令
   • Python 3.7~3.9 环境：
     加--only-binary参数强制安装预编译wheel包，跳过本地编译环节，解决绝大多数编译报错：

     pip install pyzmq==19.0.2 --only-binary=pyzmq
     

   • Python 3.10及以上环境：
     不要强行安装19.0.2，版本不兼容无可用预编译包必然安装失败，替换为无兼容bug、适配高版本Python的pyzmq 20.0.0稳定版即可，该版本不存在22.3.0的Jupyter连接故障：

     pip install pyzmq==20.0.0 --only-binary=pyzmq
     

3. 验证并重启服务
   执行命令确认安装版本符合预期：

   pip show pyzmq
   

   关闭所有残留的Jupyter进程后重启服务即可恢复正常：

   jupyter notebook stop
   jupyter notebook
   

Conda虚拟环境不要混用pip/conda安装pyzmq，直接用conda源操作即可：

conda remove -y pyzmq
# Python3.9及以下执行
conda install pyzmq=19.0.2
# Python3.10及以上执行
conda install pyzmq=20.0.0

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