推荐toree而非sparkmagic，因其是apache孵化项目且持续维护，直连spark进程、启动快、支持sparksession自动初始化，而sparkmagic依赖易失效的livy服务、不兼容spark 3.4+和python 3.11+。
直接装 toree，别碰已停更的 sparkmagic（0.13.1 是最后版本，不支持 Spark 3.4+ 和 Python 3.11+），也别手动复制 kernel 目录——90% 的连接失败、内核不显示、%%pyspark 报错都源于此。
为什么推荐 toree 而不是 sparkmagic
toree 是 Apache 孵化项目，目前唯一持续维护的 Spark 内核方案；sparkmagic 依赖 Livy REST 接口，而 HDInsight/Livy 服务端配置复杂、认证易失效，本地调试时经常卡在 Connection refused 或 401 Unauthorized；toree 直连 Spark 进程，启动快、调试直观、支持 SparkSession 自动初始化。
-
toree安装后内核名是apache_toree_scala（默认）或apache_toree_pyspark（需显式指定） -
sparkmagic的pysparkkernel实际仍走 Livy，本地没部署 Livy 就根本跑不起来 - Spark 3.3+ 默认用 Scala 2.12，
toree0.8.0+ 已适配；老版sparkmagic锁死 Scala 2.11，和新版 Spark 不兼容
安装 toree 并注册 PySpark 内核
确保已装好 spark（$SPARK_HOME 设置正确）、java（JDK 8 或 11）、jupyter（建议用 conda 环境隔离）：
- 运行
pip install toree==0.8.0（0.8.0 兼容 Spark 3.3–3.5） - 执行
jupyter toree install --spark_home=$SPARK_HOME --interpreters=PySpark --user - 检查是否生效：
jupyter kernelspec list应看到apache_toree_pyspark - 启动 notebook 后，在 kernel 菜单里选它，单元格里写
spark.version就能直接输出 Spark 版本
常见报错和绕过方法
最常卡在 java.lang.ClassNotFoundException: org.apache.spark.sql.SparkSession 或内核状态一直 “starting”：
- 确认
$SPARK_HOME指向的是完整 Spark 发行版目录（含jars/子目录），不是只下了spark-submit的精简包 - 如果用 conda 环境，
--user参数必须加，否则 kernel 注册到系统级路径，conda 环境找不到 - Mac 上若提示
zsh: command not found: jupyter，先运行source ~/.zshrc或重开终端（conda init 后未生效） - Windows 用户注意：
$SPARK_HOME要用正斜杠或双反斜杠，比如C:/spark或C:\spark，不能用C:spark
真正麻烦的从来不是装内核，而是 Spark 驱动和 executor 的 classpath 冲突——比如本地 pyarrow 版本和 Spark 自带的 Arrow JNI 不匹配，一调 toPandas() 就 segmentation fault。这类问题得看 spark.driver.extraClassPath 和日志里的 Caused by 行，不是重装内核能解决的。
