02-安装 PaddlePaddle：CPU、GPU 与环境检查入门

概述

安装 PaddlePaddle（飞桨）看起来很简单：复制官方命令，执行 pip install，然后 import paddle。但真实学习和开发中，很多问题并不是 Paddle 本身不会安装，而是环境没有先理清楚。

常见问题包括：

• 机器上有多个 Python，pip 装到了 A 环境，运行代码时却用了 B 环境。
• 本来只需要 CPU 学习，却误装了 GPU 包，排查时间被 CUDA、驱动、显卡型号消耗掉。
• 想用 GPU，但没有先确认 NVIDIA 驱动、显卡算力和 Paddle GPU 包对应关系。
• 安装成功了，但没有运行 paddle.utils.run_check()，后面写训练代码才发现环境异常。
• 在 Windows、Linux、macOS 之间照搬命令，没有注意 Python 命令名和平台差异。

这篇文章的目标不是罗列所有安装方式，而是帮你建立一套稳定的安装判断流程：

确认系统和 Python
    |
确认要装 CPU 版还是 GPU 版
    |
创建干净 Python 环境
    |
选择对应 pip 安装命令
    |
运行 Paddle 环境检查
    |
保存环境信息，开始写第一个程序

本文以 2026-07-13 官方文档展示的 PaddlePaddle 3.3.0 安装命令为例。你实际发布或执行时，建议再打开官方安装页确认最新稳定版本。

安装前判断：你到底应该装 CPU 版还是 GPU 版

初学者最容易纠结的问题是：我是不是一定要装 GPU 版？

答案很直接：刚入门学习 Paddle API、Tensor、自动微分、训练循环时，CPU 版完全够用；只有当你要训练较大模型、处理大量数据或明确需要 GPU 加速时，才优先安装 GPU 版。

场景	推荐版本	原因
学习 Paddle 基础 API	CPU 版	安装简单，排错成本低
写小规模示例、跑 MNIST、验证代码	CPU 版	性能足够，环境更稳定
本机没有 NVIDIA GPU	CPU 版	GPU 版无法发挥作用
有 NVIDIA GPU，准备训练 CNN/Transformer	GPU 版	训练速度通常明显更好
需要 TensorRT 推理或高性能部署	GPU 版	需要匹配 CUDA/TensorRT 相关能力
macOS 环境	CPU 版	官方 pip 文档当前说明 macOS 仅支持 CPU 版

如果你不确定自己该装哪个版本，先装 CPU 版。等你能稳定写出训练代码，再切换 GPU 环境。

环境要求：先确认这些条件再安装

根据飞桨官方安装文档，PaddlePaddle pip 安装需要关注操作系统、Python、pip、处理器架构和 GPU 条件。

操作系统要求

官方安装指南当前列出的 64 位操作系统包括：

• Windows 10 / 11 专业版或企业版
• Ubuntu 20.04 / 22.04 / 24.04
• almalinux 8
• macOS 12.x / 13.x / 14.x / 15.x

这里要特别注意两个点：

• 系统要是 64 位：32 位 Python 或 32 位系统不适合当前主流深度学习框架。
• 不要在过旧系统上硬装：即使某些命令能执行，后续也可能遇到动态库、编译器或驱动问题。

Python 和 pip 要求

官方文档当前要求：

• Python：3.9 / 3.10 / 3.11 / 3.12 / 3.13
• pip：20.2.2+
• Python 和 pip 都应为 64 位版本

如果你是新建学习环境，建议优先选择 Python 3.10 或 3.11。原因很简单：生态兼容性通常更稳，很多第三方库也更常在这些版本上被验证。

处理器与架构要求

官方文档提到默认安装包需要计算机支持 MKL，并且飞桨不再支持 noavx 指令集安装包。Linux 和 Windows 的官方文档也都强调要确认 Python 位数和处理器架构。

这意味着你需要知道两个信息：

• Python 是不是 64 位。
• 机器架构是不是 x86_64 / x64 / AMD64，或在特定 CPU 包场景下是 arm64。

GPU 版额外要求

如果你要安装 GPU 版，需要先确认：

• 机器有 NVIDIA GPU。
• GPU 运算能力满足官方要求，当前文档中写的是超过 7.5 的硬件设备。
• NVIDIA 驱动正常工作。
• 选择了与 Paddle 官方包索引对应的 CUDA 版本，例如 cu118、cu126、cu129、cu130。

Paddle 3.x 的一个重要变化是，官方文档说明用户安装 Paddle 时不再需要手动安装 CUDA、cuDNN、NCCL 等软件，Paddle whl 包已经自带相关依赖；但本机 GPU 驱动仍然必须满足要求。

GPU 版安装重点不是"本机装没装 CUDA Toolkit"，而是"驱动、显卡能力、Paddle GPU 包版本是否匹配"。

环境检查：先确认你正在使用哪个 Python

很多安装问题的根源是 Python 环境混乱。安装前先执行下面的检查。

Windows 环境检查

where python
python --version
python -m pip --version
python -c "import platform; print(platform.architecture()[0]); print(platform.machine())"

你希望看到的信息大致是：

Python 3.10.x / 3.11.x / 3.12.x / 3.13.x
pip 20.2.2 或更高
64bit
AMD64 / x64 / x86_64

如果 where python 输出了多条路径，要重点确认第一条是不是你打算使用的环境。Windows 上很常见的问题是：系统 Python、Anaconda Python、Microsoft Store Python、IDE 内置解释器同时存在。

Linux 环境检查

which python3
python3 --version
python3 -m pip --version
python3 -c "import platform; print(platform.architecture()[0]); print(platform.machine())"
uname -m

如果准备安装 GPU 版，还要检查 NVIDIA 驱动：

nvidia-smi

nvidia-smi 能正常显示显卡型号、驱动版本和显存信息，说明系统层面至少能识别 NVIDIA GPU。它不能单独证明 Paddle GPU 一定可用，但它是排查 GPU 环境的第一步。

macOS 环境检查

which python3
python3 --version
python3 -m pip --version
python3 -c "import platform; print(platform.architecture()[0]); print(platform.machine())"

官方 macOS pip 文档当前说明 macOS 环境仅支持 CPU 版 PaddlePaddle，并且建议使用 Python 官网提供的 Python 版本，而不是 macOS 自带 Python。

推荐做法：用独立虚拟环境安装

不建议把 Paddle 直接装进系统 Python。更稳的方式是为学习项目创建独立环境。

方案一：使用 venv

Windows：

python -m venv .venv
.\.venv\Scripts\activate
python -m pip install --upgrade pip

Linux / macOS：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

激活环境后，再执行：

python --version
python -m pip --version

这里有一个重要习惯：安装包时尽量使用 python -m pip install，不要裸用 pip install。

原因是 python -m pip 能明确告诉你：当前这个 python 对应的 pip 正在安装包。它能显著减少"装到了另一个环境"的问题。

方案二：使用 Conda

如果你已经使用 Anaconda 或 Miniconda，也可以创建环境：

conda create -n paddle310 python=3.10
conda activate paddle310
python -m pip install --upgrade pip

然后仍然使用 python -m pip install ... 安装 Paddle。

建议：初学阶段不要在同一个环境里混装太多深度学习框架。Paddle、PyTorch、TensorFlow 都可能带较重的依赖，环境越复杂，排错越难。

安装 CPU 版：最适合入门学习的方式

CPU 版适合大多数入门文章、基础 API 示例和小规模模型训练。

Windows CPU 版

python -m pip install paddlepaddle==3.3.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/

Linux CPU 版

python3 -m pip install paddlepaddle==3.3.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/

如果你已经激活了虚拟环境，并且环境里的命令是 python，也可以统一写成：

python -m pip install paddlepaddle==3.3.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/

macOS CPU 版

python3 -m pip install paddlepaddle==3.3.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/

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

安装 GPU 版：先选对 CUDA 包索引

Paddle GPU 版包名是 paddlepaddle-gpu，不是 paddlepaddle。安装时需要选择对应 CUDA 版本的官方包索引。

Linux GPU 版

CUDA 11.8：

python3 -m pip install paddlepaddle-gpu==3.3.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/

CUDA 12.6：

python3 -m pip install paddlepaddle-gpu==3.3.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/

CUDA 12.9：

python3 -m pip install paddlepaddle-gpu==3.3.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu129/

CUDA 13.0：

python3 -m pip install paddlepaddle-gpu==3.3.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu130/

Windows GPU 版

CUDA 11.8：

python -m pip install paddlepaddle-gpu==3.3.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/

CUDA 12.6：

python -m pip install paddlepaddle-gpu==3.3.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/

CUDA 12.9：

python -m pip install paddlepaddle-gpu==3.3.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu129/

怎么选择 cu118、cu126、cu129、cu130

初学者可以按下面的思路判断：

1. 优先看官方安装页：官方安装页会列出当前稳定版支持哪些 CUDA 包。
2. 看你的 NVIDIA 驱动是否足够新：驱动太旧时，新 CUDA 运行时可能无法工作。
3. 看项目依赖是否指定 CUDA 版本 ：如果公司、课程或已有项目明确要求 cu126，就按要求安装。
4. 没有特殊要求时，选择官方推荐且与驱动兼容的较新稳定包。

不要把 cu126 理解成"你必须手动安装 CUDA 12.6 Toolkit"。对普通 pip 安装来说，当前官方文档已经说明 Paddle whl 包自带 CUDA、cuDNN、NCCL 等依赖；你更需要关注的是本机 NVIDIA 驱动能否支撑对应运行时。

安装后验证：不要跳过 run_check

Paddle 官方文档给出的验证方式是进入 Python 解释器，执行：

import paddle
paddle.utils.run_check()

如果输出类似：

PaddlePaddle is installed successfully!

说明基础安装成功。

更推荐你保存一个 check_paddle_env.py 文件，用脚本一次性输出环境信息：

import platform
import sys

import paddle

print("Python:", sys.version)
print("Platform:", platform.platform())
print("Machine:", platform.machine())
print("Paddle version:", paddle.__version__)
print("Compiled with CUDA:", paddle.device.is_compiled_with_cuda())

paddle.utils.run_check()

运行：

python check_paddle_env.py

如果你安装的是 CPU 版，paddle.device.is_compiled_with_cuda() 输出 False 是正常的。

如果你安装的是 GPU 版，它应该输出 True。如果输出 False，通常说明你没有真正安装到 GPU 版包，或者当前 Python 环境加载的不是你刚安装的包。

GPU 可用性检查：确认 Paddle 真能看到 GPU

安装 GPU 版后，可以进一步执行：

import paddle

print("Paddle version:", paddle.__version__)
print("Compiled with CUDA:", paddle.device.is_compiled_with_cuda())
print("Device:", paddle.get_device())

if paddle.device.is_compiled_with_cuda():
    paddle.set_device("gpu")
    x = paddle.randn([2, 3])
    y = x * 2
    print(y)
    print("Current device:", paddle.get_device())

这段代码检查了三件事：

• Paddle 是否是 CUDA 编译版本。
• 当前设备是什么。
• 一个简单 Tensor 运算是否能在 GPU 环境下执行。

如果这段代码失败，要先看报错属于哪一类：

报错方向	常见原因	排查方式
找不到 GPU	驱动异常、没有 NVIDIA GPU、环境权限问题	先运行 nvidia-smi
CUDA 相关动态库错误	GPU 包版本、驱动、运行时不匹配	对照官方安装页选择包
is_compiled_with_cuda() 为 False	装成了 CPU 版或 Python 环境错了	python -m pip show paddlepaddle-gpu
import 失败	Python 版本、架构、pip 环境不匹配	重新检查 Python/pip 路径

GPU 环境不要只看安装命令成功，要让 Paddle 跑一次真实 Tensor 运算。

卸载和重装：先清干净包名

CPU 版和 GPU 版的包名不同：

• CPU 版：paddlepaddle
• GPU 版：paddlepaddle-gpu

卸载 CPU 版：

python -m pip uninstall paddlepaddle

卸载 GPU 版：

python -m pip uninstall paddlepaddle-gpu

如果你不确定当前环境装了什么，可以执行：

python -m pip list | grep paddle

Windows PowerShell 可以用：

python -m pip list | Select-String paddle

如果同一个环境里同时出现 paddlepaddle 和 paddlepaddle-gpu，建议卸载干净后只安装其中一个。混装会增加排查难度。

常见问题：安装成功但仍然不能正常使用

问题一：pip install 成功，但 import paddle 失败

优先检查：

python -c "import sys; print(sys.executable)"
python -m pip show paddlepaddle
python -m pip show paddlepaddle-gpu

重点看 sys.executable 和 pip show 输出的安装位置是否属于同一个环境。

问题二：安装 CPU 版后为什么不能用 GPU

因为 CPU 版包名是 paddlepaddle，它不包含 GPU 编译能力。要使用 GPU，需要安装 paddlepaddle-gpu，并选择对应 CUDA 包索引。

问题三：GPU 版安装后运行还是很慢

先确认代码是否真的跑在 GPU 上：

import paddle

print(paddle.get_device())
print(paddle.device.is_compiled_with_cuda())

然后检查是否调用了：

paddle.set_device("gpu")

另外，小规模 Tensor 运算不一定能体现 GPU 优势。GPU 适合较大批量、较大模型和高并行计算，太小的任务可能被数据搬运和调度开销抵消。

问题四：Windows 上 GPU 环境总是出问题

先把目标缩小：

1. 用 CPU 版确认 Paddle 基础 API 能跑通。
2. 用 nvidia-smi 确认驱动正常。
3. 创建全新虚拟环境，只安装 Paddle GPU 版。
4. 运行 paddle.utils.run_check() 和最小 GPU Tensor 示例。

不要一开始就在复杂项目里排查 GPU 安装问题。环境问题应该用最小脚本验证。

问题五：macOS 能不能装 GPU 版

根据当前官方 macOS pip 文档，macOS 环境仅支持 CPU 版 PaddlePaddle。学习基础 API、Tensor、自动微分和小模型训练没有问题；如果需要 GPU 训练，建议使用 Linux/Windows 的 NVIDIA GPU 环境，或使用云端 GPU 环境。

推荐安装流程：给初学者的一套稳定路径

如果你是第一次安装 Paddle，建议照这个流程走：

1. 创建一个新目录，例如 paddle-learning
2. 创建虚拟环境 .venv
3. 激活虚拟环境
4. 升级 pip
5. 安装 CPU 版 PaddlePaddle
6. 运行 paddle.utils.run_check()
7. 保存 check_paddle_env.py
8. 写第一个 Tensor 程序

对应命令如下。

Windows：

mkdir paddle-learning
cd paddle-learning
python -m venv .venv
.\.venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install paddlepaddle==3.3.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
python -c "import paddle; paddle.utils.run_check()"

Linux / macOS：

mkdir paddle-learning
cd paddle-learning
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install paddlepaddle==3.3.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
python -c "import paddle; paddle.utils.run_check()"

如果这一套能跑通，再进入下一篇文章学习 Tensor 创建、计算与设备管理。

总结

安装 PaddlePaddle 时，真正重要的是建立环境闭环：

• 确认 Python：知道你正在用哪个解释器。
• 确认 pip：知道包会装到哪个环境。
• 确认版本：Python、pip、Paddle、CPU/GPU 包要匹配。
• 确认设备：CPU 版和 GPU 版选择要符合实际硬件。
• 确认运行 ：用 paddle.utils.run_check() 和最小 Tensor 示例验证。

对初学者来说，最稳的路线是先装 CPU 版，把基础概念学通；当你开始训练更大的模型、明确需要加速时，再专门搭建 GPU 环境。