PySpark 安装保姆级教程pip、Conda、手动安装、Spark Connect 一次讲透(一)

一、什么是 PySpark？

在大数据开发领域，Apache Spark 一直是非常核心的分布式计算框架。

而对于 Python 开发者来说，最常接触的入口并不是 Scala，而是 PySpark。

很多人第一次接触 PySpark 时，会觉得它有点"拧巴"：

它叫 Python API，但底层又离不开 JVM
它可以 pip install，但又经常和 Java、Hadoop、Spark 版本扯上关系
它看起来像普通 Python 包，但有时候装完并不能马上跑起来

所以，PySpark 的难点并不在"安装命令怎么写"，而在于：

你是否理解它的运行机制和依赖关系。

这篇文章就从这个角度出发，把 PySpark 安装这件事彻底讲透。

PySpark，本质上就是 Apache Spark 的 Python API。

你可以把它简单理解成三层：

Python 代码层 ：你写 DataFrame、RDD、SQL 等逻辑
PySpark 层：负责把 Python 调用转成 Spark 可理解的操作
Spark 引擎层：真正执行分布式计算，通常运行在 JVM 上

所以 PySpark 并不是一个完全独立的 Python 大数据框架，它本质上还是依赖 Spark 的执行能力。

而 Python 之所以能和 JVM 中的 Spark 通信，中间有一个关键桥梁：

Py4J

它负责打通 Python 和 Java 之间的调用链路。

一句话概括：

PySpark = Spark 的 Python 使用方式，而不是脱离 Spark 独立存在的东西。

二、PySpark 支持哪些 Python 版本？

根据你提供的官方说明，当前支持的 Python 版本是：

bash 复制代码

Python 3.10 and above

也就是说：

Python 3.10 ✅
Python 3.11 ✅
Python 3.12 ✅
Python 3.9 及以下 ⚠️ 新版不推荐

对于新环境，建议直接使用：

text 复制代码

Python 3.10 或 3.11

这是目前比较稳妥的选择，兼容性更好，踩坑概率更低。

三、PySpark 有哪些安装方式？

PySpark 常见安装方式主要有 4 种：

使用 pip 安装
使用 Conda 安装
手动下载 Spark 发行包安装
从源码构建安装

如果你只是本地学习、开发、调试，最常用的通常是前两种。

如果你是服务器部署、离线环境或者需要精确控制版本，那么手动安装更常见。

如果你是研究 Spark 内核或者做定制化构建，那才会考虑源码安装。

下面逐个来看。

四、使用 pip 安装 PySpark

对于绝大多数 Python 开发者来说，最简单的安装方式就是：

bash 复制代码

pip install pyspark

这是最基础、最常用的一种方式。

它适合：

本地学习 Spark
快速搭建开发环境
在客户端连接远程 Spark 集群
写 Demo、教程、测试代码

1. 安装基础版

bash 复制代码

pip install pyspark

执行这条命令后，就可以获得基础 PySpark 能力。

2. 安装带扩展能力的 PySpark

PySpark 支持通过 extras 方式安装不同模块需要的依赖。

Spark SQL

bash 复制代码

pip install "pyspark[sql]"

Pandas API on Spark

bash 复制代码

pip install "pyspark[pandas_on_spark]" plotly

这里额外安装 plotly，是为了更方便做可视化。

Spark Connect

bash 复制代码

pip install "pyspark[connect]"

这种方式的优点非常明显：

你只安装自己需要的能力
环境不会一上来就很臃肿
更适合按需扩展

这也是我比较推荐的做法。

五、如何指定 Hadoop 版本？

PySpark 在 pip 安装时，还支持通过环境变量指定 Hadoop 版本。

例如：

bash 复制代码

PYSPARK_HADOOP_VERSION=3 pip install pyspark

默认情况下，官方发行版使用的是：

Hadoop 3.3
Hive 2.3

所以大多数情况下，你即使不显式指定，也会默认走这一套。

1. 使用自定义镜像加速下载

如果你网络环境一般，或者希望指定镜像源，可以这样写：

bash 复制代码

PYSPARK_RELEASE_MIRROR=http://mirror.apache-kr.org PYSPARK_HADOOP_VERSION=3 pip install pyspark

2. 查看安装详细过程

推荐加上 -v 参数：

bash 复制代码

PYSPARK_HADOOP_VERSION=3 pip install pyspark -v

这样可以更清晰地看到下载和安装过程，排查问题也更方便。

3. 支持的值有哪些？

当前 PYSPARK_HADOOP_VERSION 常见支持值包括：

without：不带 Hadoop，由用户自己提供 Hadoop 环境
3：预构建支持 Hadoop 3.3 及以上版本，默认值

不过要注意一点：

这个能力是实验性的。

也就是说，它未来可能会调整，甚至在某些小版本中发生变化。

六、什么是 `pyspark-connect`？

如果你想把 Spark Connect 作为默认方式，可以安装：

bash 复制代码

pip install pyspark-connect

这个包会自动安装：

pyspark
Spark Connect 所需依赖

它支持两类模式：

1. 使用 `spark.master`

适用于连接本地运行的 Spark Connect Server。

2. 使用 `spark.remote`

适用于远程 URI 连接，比如：

bash 复制代码

sc://localhost

可以把 Spark Connect 理解成一种更现代、更灵活的连接模型。

它把客户端和 Spark 服务端的交互做得更清晰，也更适合一些远程开发和云原生场景。

七、什么是 `pyspark-client`？

除了 pyspark-connect，还有一个：

bash 复制代码

pip install pyspark-client

这个包的特点是：

它是纯 Python 客户端
不依赖本地 JAR
不依赖本地 JRE
只支持 spark.remote
通过 URI 连接 Spark Connect 服务端

例如：

bash 复制代码

sc://localhost

这意味着什么？

意味着它比传统 PySpark 更轻量，但能力场景也更收敛。

简单区分一下：

`pyspark-connect`

自动带上 pyspark
更像"完整的 Spark Connect 使用方案"

`pyspark-client`

更轻
更纯 Python
适合只通过远程方式访问 Spark Connect 的场景

很多人第一次看文档时，最容易把这两个混在一起，这里一定要分清。

八、使用 Conda 安装 PySpark

如果你平时主要使用 Anaconda、Miniconda、Miniforge 管理 Python 环境，那么 Conda 安装 PySpark 也是一个不错的选择。

1. 创建环境

bash 复制代码

conda create -n pyspark_env

2. 激活环境

bash 复制代码

conda activate pyspark_env

3. 安装 PySpark

bash 复制代码

conda install -c conda-forge pyspark

你还可以顺便指定 Python 版本：

bash 复制代码

conda install -c conda-forge pyspark python=3.10

4. Conda 安装的优点

Conda 方式适合：

已经在使用 Conda 管理 Python 环境
项目里还有很多科学计算依赖
希望环境隔离更清晰
不想污染系统 Python

5. 需要注意什么？

官方说明里特别提到：

Conda 上的 PySpark 包并不是 Apache Spark 官方直接维护的，而是社区维护的。

这意味着：

新版一般会很快同步
但不一定和官方发布时间完全一致
个别版本可能略有延迟

6. 为什么不建议在 Conda 环境里混用 pip？

这点很重要。

虽然你在 Conda 环境里执行下面命令，技术上通常是可行的：

bash 复制代码

pip install pyspark

但官方并不推荐这么做。原因在于：

pip 不理解 conda 的依赖解析
conda 也不会完全接管 pip 装进去的包
混用后容易出现依赖冲突
以后升级、回滚、排错都很痛苦

一句话总结：

Conda 环境尽量用 Conda 装，pip 环境尽量用 pip 装。

九、手动下载安装 Spark 发行包

如果你不想通过 pip 或 Conda 安装，而是想更直接地控制 Spark 版本，那么可以使用手动下载安装的方式。

这种方式本质上是：

先下载 Spark 官方发布包
解压到本地
配置环境变量
让 Python 能找到 PySpark 与 Py4J 相关文件

1. 解压安装包

bash 复制代码

tar xzvf spark-<release>-bin-hadoop3.tgz

2. 进入目录并设置 `SPARK_HOME`

bash 复制代码

cd spark-<release>-bin-hadoop3
export SPARK_HOME=`pwd`

3. 设置 `PYTHONPATH`

bash 复制代码

export PYTHONPATH=$(ZIPS=("$SPARK_HOME"/python/lib/*.zip); IFS=:; echo "${ZIPS[*]}"):$PYTHONPATH

4. 这种方式适合什么场景？

手动安装更适合：

服务器部署
需要和指定 Spark 版本保持一致
离线环境安装
需要严格控制运行时环境
想深入理解 PySpark 目录结构和依赖关系

5. 它的缺点是什么？

缺点也很明显：

步骤多
容易漏配环境变量
对新手不太友好

但对于运维、数据平台工程师、生产环境管理者来说，这种方式反而更稳。

十、从源码安装 PySpark

如果你要从源码安装，一般不是因为"我想用 PySpark"，而是因为你要：

研究 Spark 内核
修改 Spark 源码
构建自定义版本
体验还未正式发布的功能

这种方式适合：

Spark 内核开发者
框架贡献者
企业内部做二次定制的团队

普通开发者一般没有必要一开始就选这条路。

十一、PySpark 的基础依赖有哪些？

PySpark 并不是装完就能完全独立运行的，它有一些核心依赖。

1. 必需依赖：Py4J

官方说明中明确提到：

text 复制代码

py4j >= 0.10.9.9

它的作用是：

帮助 Python 与 JVM 通信。

因为 Spark 本体是跑在 JVM 世界里的，而你写的是 Python，所以必须有一个桥梁把两边接起来，这个桥梁就是 Py4J。

2. Java 依赖

PySpark 还要求：

text 复制代码

Java 17 or later

也就是说，你需要：

安装 Java 17 或更高版本
正确设置 JAVA_HOME

这个点非常关键。

很多同学安装完 pyspark 后，一执行程序就报错，根本原因不是 PySpark 没装好，而是：

没装 Java
Java 版本太低
JAVA_HOME 没配置
PATH 配置不正确

建议安装完后先检查：

bash 复制代码

java -version

以及：

bash 复制代码

echo $JAVA_HOME

如果你是 Windows，则可以在 CMD 里执行：

bash 复制代码

java -version
echo %JAVA_HOME%

十二、不同功能模块依赖什么？

这部分是很多人最容易忽略的地方。

因为 pip install pyspark 只能保证你有"基础 PySpark 能力"，

但一旦你开始使用某些高级模块，就可能出现：

text 复制代码

ImportError
ModuleNotFoundError

所以一定要知道，不同模块有不同的依赖要求。

1. Spark Connect

安装方式：

bash 复制代码

pip install "pyspark[connect]"

需要的依赖包括：

pandas >= 2.2.0
pyarrow >= 15.0.0
grpcio >= 1.76.0
grpcio-status >= 1.76.0
googleapis-common-protos >= 1.71.0
zstandard >= 0.25.0

可选依赖：

graphviz >= 0.20

这也说明了 Spark Connect 的实现和传统方式不一样，它更依赖：

Arrow
gRPC
协议化通信能力

2. Spark SQL

安装方式：

bash 复制代码

pip install "pyspark[sql]"

需要：

pandas >= 2.2.0
pyarrow >= 15.0.0

额外增强依赖：

flameprof

如果你主要用 DataFrame、SQL 分析，那么这一组就比较常见。

3. Pandas API on Spark

安装方式：

bash 复制代码

pip install "pyspark[pandas_on_spark]"

需要：

pandas >= 2.2.0
pyarrow >= 15.0.0

可选增强依赖：

mlflow
plotly
matplotlib

其中官方更推荐 plotly。

如果你是从 Pandas 过渡到 PySpark，这一模块会非常友好，因为写法会更接近你熟悉的 Pandas 风格。

4. MLlib DataFrame-based API

安装方式：

bash 复制代码

pip install "pyspark[ml]"

需要：

numpy >= 1.22

额外增强依赖：

scipy
scikit-learn
torch
torchvision
torcheval
deepspeed

这个方向更偏机器学习和训练场景。

5. MLlib

安装方式：

bash 复制代码

pip install "pyspark[mllib]"

需要：

numpy >= 1.22

6. Declarative Pipelines

安装方式：

bash 复制代码

pip install "pyspark[pipelines]"

这一模块依赖更完整，因为它建立在 Spark SQL 与 Spark Connect 之上。依赖包括：

pandas >= 2.2.0
pyarrow >= 15.0.0
grpcio >= 1.76.0
grpcio-status >= 1.76.0
googleapis-common-protos >= 1.71.0
zstandard >= 0.25.0
pyyaml >= 3.11

可选：

graphviz >= 0.20

十三、实战：推荐的本地安装方案

如果你现在就是想在自己电脑上快速搭一个可用的 PySpark 开发环境，我给你一个非常实用的推荐。

方案 1：最简单起步版

bash 复制代码

python -m venv venv

Linux/macOS 激活：

bash 复制代码

source venv/bin/activate

Windows 激活：

bash 复制代码

venv\Scripts\activate

然后安装：

bash 复制代码

pip install pyspark

适合：

入门学习
基础练习
本地 Demo

方案 2：做 Spark SQL 分析

bash 复制代码

pip install "pyspark[sql]"

适合：

DataFrame 处理
SQL 分析
ETL 练习

方案 3：想体验类 Pandas 写法

bash 复制代码

pip install "pyspark[pandas_on_spark]" plotly

适合：

Pandas 用户迁移到分布式计算
做类 Pandas 风格的数据分析

方案 4：体验 Spark Connect

bash 复制代码

pip install "pyspark[connect]"

适合：

学习 Spark Connect
远程开发
新架构实践

安装完成后，不要急着写业务代码，先验证 Java：

bash 复制代码

java -version

确保版本至少是：

text 复制代码

Java 17+

十四、安装完成后如何验证？

安装完之后，建议先运行一个最简单的测试。

1. 进入 Python 交互环境

bash 复制代码

python

2. 执行以下代码

python 复制代码

from pyspark.sql import SparkSession

spark = SparkSession.builder \
    .appName("PySparkTest") \
    .master("local[*]") \
    .getOrCreate()

df = spark.createDataFrame(
    [(1, "Alice"), (2, "Bob"), (3, "Cindy")],
    ["id", "name"]
)

df.show()

spark.stop()

3. 如果输出类似下面内容，说明环境基本正常

text 复制代码

+---+-----+
| id| name|
+---+-----+
|  1|Alice|
|  2|  Bob|
|  3|Cindy|
+---+-----+

这一步非常重要。

很多人以为"安装命令执行成功了"就代表没问题，其实不一定。

真正能跑通一个最小示例，才说明环境是可用的。

十五、最容易踩的坑与排查方式

下面这部分，几乎每个新手都会遇到，建议收藏。

1. 报错：找不到 Java / `JAVA_HOME` 未设置

常见现象：

启动 SparkSession 时报错
提示找不到 Java
提示 JAVA_HOME is not set

排查方式：

bash 复制代码

java -version

如果提示命令不存在，说明 Java 根本没装。

如果版本太低，也要升级。

同时检查环境变量：

Linux/macOS：

bash 复制代码

echo $JAVA_HOME

Windows：

bash 复制代码

echo %JAVA_HOME%

2. 报错：Python 版本不兼容

如果你用的是比较旧的 Python，比如 3.8、3.9，那么新版 PySpark 可能装不上或者运行异常。

建议直接升级到：

Python 3.10
Python 3.11

3. 报错：缺少 `pandas`、`pyarrow`、`grpcio`

这种情况通常是因为你只安装了基础版：

bash 复制代码

pip install pyspark

但你实际却在用：

Spark SQL 增强能力
Pandas API on Spark
Spark Connect

这时就要按模块补装依赖，例如：

bash 复制代码

pip install "pyspark[sql]"

或者：

bash 复制代码

pip install "pyspark[connect]"

4. Conda 和 pip 混装导致环境混乱

这是非常高频的问题。

比如你先：

bash 复制代码

conda install pyspark

后来又：

bash 复制代码

pip install pandas pyarrow grpcio

表面上看没问题，实际后面升级时极容易冲突。

建议策略很简单：

用 Conda 就尽量全程 Conda
用 pip 就尽量全程 pip

5. 误解 `pyspark-connect` 和 `pyspark-client`

很多人会误以为这两个是一个东西，其实不是：

`pyspark-connect`

更完整，更偏"正式使用 Spark Connect 的一整套依赖方案"

`pyspark-client`

更轻量，纯 Python，适合仅做远程 URI 连接

这个一定要分清。

十六、安装方式怎么选？一张思路图搞定

如果你现在还在纠结该选哪种安装方式，可以直接按下面的思路判断。

1. 我只是学习 PySpark

选：

bash 复制代码

pip install pyspark

2. 我平时就用 Conda 管环境

选：

bash 复制代码

conda install -c conda-forge pyspark

3. 我需要和线上 Spark 版本严格一致

选：

手动下载 Spark 发行包
配置 SPARK_HOME
配置 PYTHONPATH
配置 JAVA_HOME

4. 我在研究 Spark 源码或做定制开发

选：

从源码构建

其实说白了：

学习阶段，先跑起来最重要；生产阶段，可控性最重要。

十七、FAQ：几个高频问题一次答清

Q1：安装 PySpark 还需要单独安装 Spark 吗？

如果你使用的是：

bash 复制代码

pip install pyspark

那么通常不需要你手动再下载一份 Spark 压缩包。

因为 pip 安装的 PySpark 已经包含了相关运行时支持。

但如果你走的是：

手动下载 Spark 发行版
服务器统一部署
特定版本控制

那就需要自己准备 Spark 包。

Q2：安装 PySpark 一定要装 Hadoop 吗？

不一定。

大多数本地学习场景下，不需要你单独装 Hadoop 集群。

很多时候，PySpark 的预构建包已经能满足本地使用需求。

Q3：安装 PySpark 一定要装 Java 吗？

是的，绝大多数常规 PySpark 场景都需要 Java。

因为 Spark 本身运行在 JVM 之上。

只有某些更轻量、纯 Python 的 Spark Connect Client 场景，才会减少对本地 JRE 的依赖。

Q4：我只想写 SQL，装哪个最合适？

Q5：我本来是 Pandas 用户，想平滑过渡到 PySpark，装哪个？

Q6：生产环境推荐 pip 还是手动安装？

如果是企业生产环境，一般更倾向：

手动下载安装包
统一版本控制
环境变量显式配置

因为这样更稳，更方便治理。

十八、总结

PySpark 安装这件事，表面看像是"敲一条命令"，但真正影响你后续开发体验的，其实是对以下三件事的理解：

1. 你要解决什么场景？

本地学习
开发调试
客户端连接
服务器部署
源码研究

2. 你需要哪些功能模块？

基础 PySpark
Spark SQL
Pandas API on Spark
Spark Connect
MLlib
Declarative Pipelines

3. 你的环境准备好了没有？

Python 3.10+
Java 17+
JAVA_HOME
正确的扩展依赖

所以，PySpark 安装真正的关键不是"命令会不会背"，而是：

知道自己装的是什么、为什么这样装、装完以后靠什么跑起来。

PySpark 安装保姆级教程pip、Conda、手动安装、Spark Connect 一次讲透(一)

一、什么是 PySpark？

二、PySpark 支持哪些 Python 版本？

三、PySpark 有哪些安装方式？

四、使用 pip 安装 PySpark

1. 安装基础版

2. 安装带扩展能力的 PySpark

Spark SQL

Pandas API on Spark

Spark Connect

五、如何指定 Hadoop 版本？

1. 使用自定义镜像加速下载

2. 查看安装详细过程

3. 支持的值有哪些？

六、什么是 pyspark-connect？

1. 使用 spark.master

2. 使用 spark.remote

七、什么是 pyspark-client？

pyspark-connect

pyspark-client

八、使用 Conda 安装 PySpark

1. 创建环境

2. 激活环境

3. 安装 PySpark

4. Conda 安装的优点

5. 需要注意什么？

6. 为什么不建议在 Conda 环境里混用 pip？

九、手动下载安装 Spark 发行包

1. 解压安装包

2. 进入目录并设置 SPARK_HOME

3. 设置 PYTHONPATH

4. 这种方式适合什么场景？

5. 它的缺点是什么？

十、从源码安装 PySpark

十一、PySpark 的基础依赖有哪些？

1. 必需依赖：Py4J

2. Java 依赖

十二、不同功能模块依赖什么？

1. Spark Connect

2. Spark SQL

3. Pandas API on Spark

4. MLlib DataFrame-based API

5. MLlib

6. Declarative Pipelines

十三、实战：推荐的本地安装方案

方案 1：最简单起步版

方案 2：做 Spark SQL 分析

方案 3：想体验类 Pandas 写法

方案 4：体验 Spark Connect

十四、安装完成后如何验证？

1. 进入 Python 交互环境

2. 执行以下代码

3. 如果输出类似下面内容，说明环境基本正常

十五、最容易踩的坑与排查方式

1. 报错：找不到 Java / JAVA_HOME 未设置

2. 报错：Python 版本不兼容

3. 报错：缺少 pandas、pyarrow、grpcio

4. Conda 和 pip 混装导致环境混乱

5. 误解 pyspark-connect 和 pyspark-client

pyspark-connect

pyspark-client

十六、安装方式怎么选？一张思路图搞定

1. 我只是学习 PySpark

2. 我平时就用 Conda 管环境

3. 我需要和线上 Spark 版本严格一致

4. 我在研究 Spark 源码或做定制开发

十七、FAQ：几个高频问题一次答清

Q1：安装 PySpark 还需要单独安装 Spark 吗？

Q2：安装 PySpark 一定要装 Hadoop 吗？

Q3：安装 PySpark 一定要装 Java 吗？

Q4：我只想写 SQL，装哪个最合适？

Q5：我本来是 Pandas 用户，想平滑过渡到 PySpark，装哪个？

Q6：生产环境推荐 pip 还是手动安装？

十八、总结

1. 你要解决什么场景？

2. 你需要哪些功能模块？

3. 你的环境准备好了没有？

六、什么是 `pyspark-connect`？

1. 使用 `spark.master`

2. 使用 `spark.remote`

七、什么是 `pyspark-client`？

`pyspark-connect`

`pyspark-client`

2. 进入目录并设置 `SPARK_HOME`

3. 设置 `PYTHONPATH`

1. 报错：找不到 Java / `JAVA_HOME` 未设置

3. 报错：缺少 `pandas`、`pyarrow`、`grpcio`

5. 误解 `pyspark-connect` 和 `pyspark-client`

`pyspark-connect`

`pyspark-client`