适配场景：Jetson Orin 系列（Orin Nano/NX/AGX），L4T R36.x/ JetPack 6.x，Ubuntu 22.04 aarch64

Jetson 平台 CUDA + PyTorch + ROS2 安装指南

适配场景：Jetson Orin 系列（Orin Nano/NX/AGX），L4T R36.x/ JetPack 6.x，Ubuntu 22.04 aarch64

- 硬件型号：NVIDIA Jetson Orin Nano Developer Kit
- 底层系统 (L4T)：R36.5.0
- JetPack 版本：JetPack 6.2.2

一、系统初始化与 CUDA 安装

1. 恢复系统完整工具链（精简系统必做）

Jetson 出厂默认 minimized 精简系统缺失大量基础开发工具，安装各类依赖前优先恢复：

sudo unminimize

全程按 y 确认，执行完成后重连 SSH 终端生效。

2. 确认硬件与系统版本

查看硬件型号

cat /proc/device-tree/model

查看 L4T / JetPack 版本

cat /etc/nv_tegra_release

版本对应关系：

R36.x → JetPack 6.x → 配套 CUDA 12.x
R35.x → JetPack 5.x → 配套 CUDA 11.4
R32.x → JetPack 4.6.x → 配套 CUDA 10.2

3. 安装 CUDA 工具链

两种安装方式按需选择：

方式一：完整安装 JetPack 元包（推荐） 包含 CUDA、cuDNN、TensorRT、多媒体编解码等全套官方组件

sudo apt update
sudo apt install nvidia-jetpack -y

方式二：仅安装 CUDA 开发包（轻量推理场景） 只装 CUDA 核心工具与开发库，节省磁盘空间

sudo apt update
sudo apt install nvidia-cuda-dev -y

4. 配置 CUDA 环境变量

编辑用户环境配置文件：

nano ~/.bashrc

在文件末尾追加以下内容（适配 Jetson aarch64 目录结构）：

export CUDA_HOME=/usr/local/cuda
export PATH=/usr/local/cuda/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda/lib64:/usr/local/cuda/targets/aarch64-linux/lib:$LD_LIBRARY_PATH

保存退出（Ctrl+O 回车确认，Ctrl+X 退出），刷新配置使其立即生效：

source ~/.bashrc

5. 基础安装验证

nvcc -V

正常输出 CUDA 版本号（如 release 12.6）即为基础安装成功。

6. 补装 cuDSS 组件（解决 `libcudss.so.0` 缺失报错）

Jetson 默认 apt 源不包含 CUDA 稀疏求解库 cuDSS，高版本 PyTorch 依赖该库，需通过 NVIDIA 官方本地源单独安装：

下载官方本地源 deb 包

wget https://developer.download.nvidia.com/compute/cudss/0.7.1/local_installers/cudss-local-tegra-repo-ubuntu2204-0.7.1_0.7.1-1_arm64.deb

安装本地源配置

sudo dpkg -i cudss-local-tegra-repo-ubuntu2204-0.7.1_0.7.1-1_arm64.deb

导入 GPG 签名密钥

sudo cp /var/cudss-local-tegra-repo-ubuntu2204-0.7.1/cudss-*-keyring.gpg /usr/share/keyrings/

安装 cuDSS 运行时库

sudo apt update
sudo apt install -y libcudss0-cuda-12
# 如需编译自定义算子，额外安装开发包
sudo apt install -y libcudss0-dev-cuda-12

❌ 避坑：不存在 libcudss-dev-12-6 这类包名，Jetson 平台统一使用 libcudss0-cuda-12 格式

配置系统动态库搜索路径

echo "/usr/lib/aarch64-linux-gnu/libcudss/12" | sudo tee /etc/ld.so.conf.d/libcudss-cuda12.conf
sudo ldconfig

验证库文件

ldconfig -p | grep libcudss

输出 libcudss.so.0 对应路径即为配置成功。

二、Python 虚拟环境与 Jetson 版 PyTorch 安装

🔴 核心原则：不推荐使用 Miniconda/Anaconda Conda 自带独立 Python 解释器，无法直接导入系统 apt 安装的 ROS2 rclpy 库，且 aarch64 架构预编译包极少，兼容性问题多。统一使用系统 Python + venv 虚拟环境，搭配 --system-site-packages 参数实现 ROS2 与推理环境共存。

1. 安装 venv 工具

sudo apt update
sudo apt install python3.10-venv python3-pip -y

2. 创建虚拟环境（关键参数不可省略）

python3 -m venv ~/crayfish_venv --system-site-packages

--system-site-packages 作用：虚拟环境优先使用内部安装的包，缺失时自动读取系统 Python 库（包含 ROS2 的 rclpy），实现推理节点与 ROS 通信无缝衔接。

3. 激活虚拟环境

source ~/crayfish_venv/bin/activate

终端前缀出现 (crayfish_venv) 即为激活成功。

4. 升级 pip

pip install -U pip

5. 安装 Jetson 适配版 PyTorch（二选一）

方式 A：在线安装（jetson-ai-lab 专属源）

适配 JetPack 6.x + CUDA 12.x，自动匹配 aarch64 架构：

pip install torch torchvision --index-url https://pypi.jetson-ai-lab.io/jp6/cu126

缺点：海外源下载速度较慢，适合网络环境较好的场景

方式 B：离线 whl 安装（推荐，速度稳定）

PC 端提前下载对应架构的 whl 包（必须下载 linux_aarch64 版本，切勿下载 x86_64 版本）
下载源：https://pypi.jetson-ai-lab.io/jp6/cu126 必下文件：
- torch-xxx-cp310-cp310-linux_aarch64.whl
- torchvision-xxx-cp310-cp310-linux_aarch64.whl
通过 scp 将文件传输到 Jetson 板子（PC 终端执行）

scp torch-*.whl torchvision-*.whl ts1@10.10.150.46:/home/ts1/Downloads/

cd ~/Downloads
pip install torch-*.whl torchvision-*.whl

6. 验证 PyTorch 与 CUDA 可用性

python3 -c "
import torch
import torchvision
print('torch版本:', torch.__version__)
print('torchvision版本:', torchvision.__version__)
print('CUDA可用:', torch.cuda.is_available())
print('CUDA版本:', torch.version.cuda)
"

✅ 核心校验项：CUDA可用: True，代表 GPU 加速能力正常。

7. 安装推理依赖（以 YOLO 为例）

7.1 安装依赖

# 安装可由 pip 管理的依赖
python -m pip install \
-i https://pypi.tuna.tsinghua.edu.cn/simple \
"numpy==1.26.4" \
"PyYAML>=6.0" \
"polars>=0.20.0" \
"nvidia-ml-py>=12.0.0" \
"ultralytics-thop>=2.1.6"

# 跳过依赖解析，避免自动安装 opencv-python
python -m pip install \
-i https://pypi.tuna.tsinghua.edu.cn/simple \
--no-deps \
"ultralytics==8.4.113"

🚫 禁止执行 pip install opencv-python Jetson 系统自带硬件加速版 OpenCV，pip 安装的纯 CPU 版本会覆盖原库，丢失 GPU 加速能力。

# 查看虚拟环境是否额外安装了 PyPI OpenCV
  python -m pip show opencv-python opencv-python-headless

# 如果显示了其中任意一个（有输出），并且 Location 位于 crayfish_venv，将其卸载，保留 Jetson 系统 OpenCV：
  python -m pip uninstall -y opencv-python opencv-python-headless

✅ NumPy 固定为 1.26.4 避免 NumPy 2.x 与系统 Matplotlib、OpenCV、ROS 2 扩展发生二进制 ABI 冲突。

7.2 验证 YOLO 是否安装：

python3 -c "from ultralytics import YOLO; print('✅ YOLO加载成功')"

如果报错, 大概率是: 虚拟环境里的 NumPy 2.2.6 与 Jetson 系统 Matplotlib 3.5.1 的二进制 ABI 不兼容。将 NumPy 降到兼容的 1.x：

python -m pip install \
-i https://pypi.tuna.tsinghua.edu.cn/simple \
--force-reinstall \
"numpy==1.26.4"

7.3 验证yolo是否可以跑通推理

yolo train data=coco8.yaml model=yolo26n.pt epochs=10 lr0=0.01

如果可以训练，但是推理时报错，大概率是没有编译 CUDA 版 torchvision::nms 算子先直接验证当前 CUDA NMS，复制这一条单行命令：

python -c 'import torch,torchvision;print("Torch:",torch.__version__);print("TorchVision:",torchvision.__version__,torchvision.__file__); boxes=torch.tensor([[0.,0.,10.,10.],[1.,1.,9.,9.]],device="cuda");scores=torch.tensor([0.9,0.8],device="cuda");print("CUDANMS:",torchvision.ops.nms(boxes,scores,0.5))'

当前环境预计会再次出现同一个错误。然后强制重新安装 Jetson AI Lab 提供的对应版本：

python -m pip install \
    --force-reinstall \
    --no-cache-dir \
    --no-deps \
    "torchvision==0.23.0" \
    --index-url https://pypi.jetson-ai-lab.io/jp6/cu126

这里：

—force-reinstall：即使版本相同，也重新安装。
—no-cache-dir：避免继续使用之前缓存的普通 ARM64 wheel。
—no-deps：防止它重新安装 Torch 或升级 NumPy。
torchvision 0.23.0 与现有的 torch 2.8.0 是对应组合。

安装后再次运行 CUDA NMS 测试：

 python -c 'import torch,torchvision; boxes=torch.tensor([[0.,0.,10.,10.],[1.,1.,9.,9.]],device="cuda");scores=torch.tensor([0.9,0.8],device="cuda");print("Torch:",torch.__version__);print("TorchVision:",torchvision.__version__);print("CUDANMS:",torchvision.ops.nms(boxes,scores,0.5)); print("✅ CUDA NMS 正常")'

成功时应看到类似：CUDA NMS: tensor([0], device='cuda:0')✅ CUDA NMS 正常

修复后单独执行验证即可：

  yolo val \
    model=/home/ts1/runs/detect/train-3/weights/best.pt \
    data=coco8.yaml \
    device=0

三、ROS2 Humble 安装（小鱼一键脚本）

1. 执行一键安装脚本

wget http://fishros.com/install -O fishros && . fishros

按照菜单提示选择：ROS2 → Humble 版本 → 安装类型按需选择：

Jetson 无头部署、仅运行节点：选 ros-base 基础版（资源占用更低）
接屏幕本地调试：选桌面完整版

脚本会自动配置国内镜像源并完成安装。

2. 刷新环境变量

安装完成后脚本会自动写入环境变量，手动刷新生效：

source ~/.bashrc

3. 验证 ROS2 基础安装

ros2 --version

输出版本号即为安装成功。

4. 验证虚拟环境内 ROS2 Python 接口可用性

激活虚拟环境后测试 rclpy 导入：

source ~/crayfish_venv/bin/activate
python3 -c "import rclpy; print('✅ rclpy加载成功，ROS2 Python接口可用')"

✅ 导入无报错，即可在虚拟环境中同时运行 YOLO 推理与 ROS2 节点。

5.总体验收

source ~/crayfish_venv/bin/activate
python -c 'import rclpy, cv2, numpy, torch; from ultralytics import YOLO; print("ROS 2: OK"); print("OpenCV:",cv2.__version__, cv2.__file__); print("NumPy:", numpy.__version__); print("Torch:", torch.__version__); print("CUDA:",torch.cuda.is_available()); print("YOLO: 加载成功")'

预期输出：

ROS 2: OK
OpenCV: 4.8.0 /usr/lib/python3.10/dist-packages/cv2/__init__.py
NumPy: 1.26.4
Torch: 2.8.0
CUDA: True
YOLO: 加载成功

其他操作

日常快捷环境加载

编辑 ~/.bashrc 追加一键加载函数：

function env-crayfish(){
  source ~/crayfish_venv/bin/activate
  source /opt/ros/humble/setup.bash
  echo "✅ 环境加载完成：推理环境 + ROS2 Humble"
}

生效后，新开终端输入 env-crayfish 即可一键完成全部环境加载。

换回官方源完整执行步骤

当需要更新cuda环境等，由于安装ros2是更换了系统源，以下方式为了切回官方下是Jetson Orin Nano / JetPack 6.2.2 (L4T R36.5) 恢复原厂官方 apt 源 + 规范签名配置的完整可执行命令集，按顺序逐条执行即可。

查看当前系统源

grep -v '^#' /etc/apt/sources.list | grep -v '^$'

官方源为下面的地址，如果不是说明已经更换过系统源

deb http://ports.ubuntu.com/ubuntu-ports/ jammy main restricted universe multiverse
deb http://ports.ubuntu.com/ubuntu-ports/ jammy-updates main restricted universe multiverse
deb http://ports.ubuntu.com/ubuntu-ports/ jammy-security main restricted universe multiverse
deb http://ports.ubuntu.com/ubuntu-ports/ jammy-backports main restricted universe multiverse

下面是完整的执行步骤：

1. 备份现有源配置（必做，防止误操作）

sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak.$(date +%Y%m%d)
sudo cp -r /etc/apt/sources.list.d /etc/apt/sources.list.d.bak.$(date +%Y%m%d)

2. 恢复 Ubuntu 系统官方主源（ports 架构源）

sudo tee /etc/apt/sources.list <<'EOF'
deb http://ports.ubuntu.com/ubuntu-ports/ jammy main restricted universe multiverse
deb http://ports.ubuntu.com/ubuntu-ports/ jammy-updates main restricted universe multiverse
deb http://ports.ubuntu.com/ubuntu-ports/ jammy-security main restricted universe multiverse
deb http://ports.ubuntu.com/ubuntu-ports/ jammy-backports main restricted universe multiverse
EOF

3. 清理 FishROS / 小鱼安装工具添加的第三方 ROS 源

sudo rm -f /etc/apt/sources.list.d/ros2.list
sudo rm -f /etc/apt/sources.list.d/fishros.list
sudo rm -f /etc/apt/sources.list.d/fishros-*.list

4. 配置 NVIDIA Jetson L4T 官方源（带签名校验，规范写法）

# 创建密钥目录
sudo mkdir -p /etc/apt/keyrings

# 下载并导入官方GPG公钥
curl -fsSL https://repo.download.nvidia.com/jetson/jetson-ota-public.asc | sudo gpg --dearmor -o /etc/apt/keyrings/nvidia-jetson.gpg

# 写入带签名绑定的官方源
sudo tee /etc/apt/sources.list.d/nvidia-l4t-apt-source.list <<'EOF'
deb [signed-by=/etc/apt/keyrings/nvidia-jetson.gpg] https://repo.download.nvidia.com/jetson/common r36.5 main
deb [signed-by=/etc/apt/keyrings/nvidia-jetson.gpg] https://repo.download.nvidia.com/jetson/t234 r36.5 main
EOF

5. 更新源并验证生效

sudo apt update

Jetson 平台 CUDA + PyTorch + ROS2 安装指南

Jetson 平台 CUDA + PyTorch + ROS2 安装指南

一、系统初始化与 CUDA 安装

1. 恢复系统完整工具链（精简系统必做）

2. 确认硬件与系统版本

3. 安装 CUDA 工具链

4. 配置 CUDA 环境变量

5. 基础安装验证

6. 补装 cuDSS 组件（解决 libcudss.so.0 缺失报错）

二、Python 虚拟环境与 Jetson 版 PyTorch 安装

1. 安装 venv 工具

2. 创建虚拟环境（关键参数不可省略）

3. 激活虚拟环境

4. 升级 pip

5. 安装 Jetson 适配版 PyTorch（二选一）

方式 A：在线安装（jetson-ai-lab 专属源）

方式 B：离线 whl 安装（推荐，速度稳定）

6. 验证 PyTorch 与 CUDA 可用性

7. 安装推理依赖（以 YOLO 为例）

7.1 安装依赖

7.2 验证 YOLO 是否安装：

7.3 验证yolo是否可以跑通推理

三、ROS2 Humble 安装（小鱼一键脚本）

1. 执行一键安装脚本

2. 刷新环境变量

3. 验证 ROS2 基础安装

4. 验证虚拟环境内 ROS2 Python 接口可用性

5.总体验收

其他操作

日常快捷环境加载

换回官方源完整执行步骤

1. 备份现有源配置（必做，防止误操作）

2. 恢复 Ubuntu 系统官方主源（ports 架构源）

3. 清理 FishROS / 小鱼安装工具添加的第三方 ROS 源

4. 配置 NVIDIA Jetson L4T 官方源（带签名校验，规范写法）

5. 更新源并验证生效

6. 补装 cuDSS 组件（解决 `libcudss.so.0` 缺失报错）