问题现象

在 Arch Linux 系统上，使用 Python 3.14.6 创建虚拟环境后，执行 pip install paddlepaddle 或使用百度官方 CPU 镜像源安装时，均报错：

ERROR: No matching distribution found for paddlepaddle

常见排查步骤（如更换镜像源、升级 pip、重建虚拟环境）均无效。

根本原因

问题根源在于 Python 版本不兼容，而非网络问题。

• Arch Linux 滚动更新特性：系统默认的 python3 已更新至 Python 3.14.6（2025年10月发布）。
• PaddlePaddle 的 PyPI 构建限制：PaddlePaddle 官方发布的 wheel 包目前最高仅支持到 cp313（即 Python 3.13），尚未提供针对 Python 3.14（cp314）的预编译二进制包。
• pip 的匹配逻辑：当 pip 在当前 Python 解释器版本下找不到兼容的 wheel 时，就会抛出 "No matching distribution found" 错误，即使网络通畅、包名正确。

可以通过以下命令验证：

python3 --version  # 输出 Python 3.14.6
pip index versions paddlepaddle  # 同样报错，但 pip 能正常连接网络（例如提示 pip 可升级）

解决方案

核心思路：降级或使用兼容的 Python 版本。

方案一：使用 Conda 环境（推荐）

Conda 可以独立管理 Python 版本，避免与系统 Python 冲突。

# 1. 安装 Miniconda（如果尚未安装）
# 2. 创建一个使用 Python 3.11 的环境（PaddlePaddle 官方测试较充分的版本）
conda create -n paddle-env python=3.11
conda activate paddle-env
3. 安装 PaddlePaddle CPU 版本
pip install paddlepaddle -i https://www.paddlepaddle.org.cn/packages/stable/cpu/

方案二：使用 pyenv 管理多版本 Python

在 Arch 上安装并切换到一个受支持的 Python 版本。

# 1. 安装 pyenv
git clone https://github.com/pyenv/pyenv.git ~/.pyenv
# 按照官方文档配置 shell 环境变量
2. 安装 Python 3.11
pyenv install 3.11.9
3. 在项目目录中局部使用该版本
cd ~/your-project
pyenv local 3.11.9
4. 创建虚拟环境并安装
python -m venv venv
source venv/bin/activate
pip install paddlepaddle

方案三：使用 Docker（最彻底的环境隔离）

直接使用 PaddlePaddle 官方提供的 Docker 镜像，无需担心宿主机 Python 版本。

# 拉取 CPU 版本的 PaddlePaddle 镜像
docker pull paddlepaddle/paddle:latest-cpu
运行容器并进入交互环境
docker run -it --name paddle-cpu paddlepaddle/paddle:latest-cpu /bin/bash

在容器内，Python 环境、PaddlePaddle 及依赖均已配置完成，可直接开始开发或训练。

方案四：从源码编译（适用于高级用户）

如果必须在 Python 3.14 上运行，可以尝试从源码编译 PaddlePaddle。此过程耗时较长，且可能遇到依赖问题。

# 克隆 PaddlePaddle 仓库
git clone https://github.com/PaddlePaddle/Paddle.git
cd Paddle
根据官方编译指南配置环境并编译
详见：https://www.paddlepaddle.org.cn/documentation/docs/zh/install/compile/fromsource_cn.html

方案五：使用 uv 安装旧版 Python（绕过 wheel 缺失）

如果你希望使用一个独立的 Python 版本管理器，并且不想影响系统 Python，可以尝试 uv（Astral 开发的 Python 版本管理器）。它能快速下载并安装特定版本的 Python（如 3.12），并创建独立的虚拟环境，全程不触碰系统 Python。

以下命令均实测通过：

# 1. 安装 uv
pip install uv
2. 下载 Python 3.12（python-build-standalone，GitHub 发行物）
uv python install 3.12
输出: cpython-3.12.14-linux-x86_64-gnu (python3.12)
3. 用 3.12 建独立 venv
uv venv --python 3.12 ~/train-venv-py312
4. 安装飞桨等（注意：uv 建的 venv 默认没有 pip！）
uv pip install --python ~/train-venv-py312/bin/python paddlepaddle librosa scikit-learn
5. 验证
~/train-venv-py312/bin/python -c "import paddle, librosa; print(paddle.version, librosa.version)"
输出: paddle 3.3.1 | librosa 1.0.0

两个必踩的坑

• 坑一：uv venv 不带 pip。直接执行 ~/train-venv-py312/bin/pip install 会报 No such file or directory。必须用 uv pip install --python <venv>/bin/python 把包装进该环境。
• 坑二：GitHub 下载慢或连不上。uv python install 卡住时，给远端配 Mac 本机代理（代理需开启局域网共享）：
  export http_proxy=http://192.168.50.2:7890 https_proxy=http://192.168.50.2:7890

附带教训：远程清理后台脚本时，pkill -f 'train-setup.sh' 会把当前 ssh 会话一起杀掉（命令行里含相同字符串）。改用正则绕开自身：pkill -f 'train-setup[.]sh'。

总结与建议

• 优先推荐方案一（Conda）：环境隔离性好，Python 版本管理灵活，最接近官方测试环境。
• 临时验证可用方案二（pyenv）：适合已在开发流程中使用 pyenv 的用户。
• 追求环境纯净用方案三（Docker）：避免污染宿主机环境，适合生产或团队协作。
• 慎用方案四（源码编译）：仅当你有特定需求且熟悉 C++/CUDA 编译工具链时尝试。

对于 Arch Linux 用户，在享受滚动更新带来的新特性时，也需注意此类深度学习框架对 Python 版本的支持滞后问题。建议为 AI/ML 项目创建独立、版本固定的虚拟环境，避免与系统全局 Python 强绑定。

落地结论

可复用的“新 Python 装不了飞桨”解法核心一句话：Python 太新没有 wheel，就用 uv 装一个受支持的旧版解释器，把包装进它自己的 venv，全程不碰系统 Python。

适用范围

• Arch 及各类滚动发行版：系统 Python 永远最新，国产框架（飞桨等）的 wheel 常常滞后一两个版本。
• 任何“网络正常却 No matching distribution found”的情况。
• 一台机器同时需要多个 Python 版本环境。

不适用：有 NVIDIA GPU 的机器建议直接用官方 GPU 包（需对应 CUDA 版本）；纯 Python 依赖的库不需要这套方案。

三类读者速查

人类开发者

先用 python3 --version 确认版本。遇到 No matching distribution found 时，优先怀疑“Python 版本没对应 wheel”而不是网络；自查命令：pip index versions paddlepaddle。

对话式 AI

问法：“Arch 上 pip install paddlepaddle 报 No matching distribution found 怎么办？”

回答要点：先查 python3 --version 是否 ≥3.14；是则用 uv python install 3.12 建旧版解释器 + uv venv + uv pip install，绕过系统 Python。

代码 Agent

可复制执行脚本：

pip install uv
uv python install 3.12
uv venv --python 3.12 ~/venv-py312
uv pip install --python ~/venv-py312/bin/python paddlepaddle librosa
~/venv-py312/bin/python -c "import paddle; print(paddle.__version__)"