RKNN Toolkit2安装避坑指南：解决No module named rknn

1. 从一次真实的踩坑说起为什么“No module named rknn”这么难缠如果你正在把深度学习模型往瑞芯微Rockchip的NPU平台上部署大概率绕不开RKNN Toolkit2这套工具链。它负责把训练好的模型转换成RKNN格式再交给板端NPU推理。听起来流程清晰但真正动手装环境的时候很多人第一步就卡住了——终端里敲下python输入from rknn.api import RKNN回车屏幕上冷冰冰地弹出一行ModuleNotFoundError: No module named rknn这个报错本身不复杂就是Python找不到名为rknn的模块。但它的难缠之处在于你明明已经pip install过了甚至可能装了好几遍它依然报同样的错。更让人抓狂的是网上搜到的解决方案五花八门有人让你换Python版本有人让你装wheel包有人让你改环境变量试了一圈还是不行。我自己在给RK3588和RK3568两块板子配环境的时候前前后后在这个问题上耗了将近两天。后来复盘发现这个报错背后其实藏着三个典型的“陷阱”每一个都会导致模块装不上或者装上了却找不到。这篇文章就把这三个陷阱拆开讲清楚从根因到排查手法到最终解决一步步来。不管你是刚接触RKNN的新手还是已经装过几次但偶尔翻车的老手都能从里面找到可以直接复用的排查思路。需要提前说明的是RKNN Toolkit2的安装对系统环境、Python版本、依赖库版本都有比较严格的要求它不是那种pip install一把梭就能搞定的普通Python包。理解这一点后面的很多问题就顺了。2. 陷阱一Python版本与架构不匹配装了也白装2.1 RKNN Toolkit2到底支持哪些Python版本这是最容易踩的第一个坑。很多人习惯性地用系统自带的Python或者用conda随便建一个环境就开始装结果版本不对pip虽然显示安装成功但装进去的东西根本没法用。RKNN Toolkit2对Python版本有明确要求。根据瑞芯微官方文档和实际测试目前主流版本1.5.x到2.x支持的Python版本集中在3.6到3.10之间其中3.8和3.10是最稳妥的选择。Python 3.11及以上版本在部分RKNN Toolkit2版本中会出现依赖不兼容的问题尤其是numpy和onnx这两个核心依赖的版本约束会冲突。你可以用下面这行命令确认当前Python版本python3 --version如果输出是3.11或更高建议直接换一个3.8或3.10的环境不要硬扛。我试过在Python 3.11上强行装RKNN Toolkit2pip能装完但导入时会在rknn.api内部报ImportError错误信息指向某个C扩展加载失败排查起来非常费劲。2.2 系统架构x86和ARM的区别不能忽略第二个容易忽略的点是系统架构。RKNN Toolkit2分两个使用场景PC端x86_64用于模型转换、量化、仿真推理。这是大多数人在Ubuntu主机上用的场景。板端aarch64用于在RK3588、RK3568等开发板上直接推理。这两个场景对应的安装包完全不同。如果你在x86的Ubuntu上装了aarch64的wheel包pip会直接报错说平台不兼容。反过来在板子上装x86的包同样不行。确认架构的命令uname -m输出x86_64就是PC端输出aarch64就是板端。这一步看起来简单但我见过不少人从网上随便下载了一个wheel包就装根本没注意架构结果卡在安装阶段就开始怀疑人生。2.3 虚拟环境的选择conda还是venv我个人的建议是用conda建一个独立的Python 3.8环境原因有三conda可以精确指定Python小版本比如python3.8.10避免系统Python升级带来的意外。conda环境隔离性好不会污染系统Python出问题直接删环境重来。RKNN Toolkit2的某些依赖如numpy对版本敏感conda在依赖解析上比pip更稳。创建环境的命令conda create -n rknn python3.8.10 conda activate rknn如果你不想用conda用python3.8 -m venv rknn_env也可以但前提是系统里确实装了Python 3.8并且venv模块可用。注意不要用root用户直接往系统Python里装RKNN Toolkit2。一旦依赖冲突修复起来可能要重装系统Python代价太大。2.4 一个容易被忽略的细节pip版本pip版本太老也会导致wheel包安装失败。建议先把pip升到较新版本pip install --upgrade pip但也不要升到最新版就完事某些RKNN Toolkit2版本对pip有上限要求。实测下来pip 21.x到23.x都比较稳。如果升到24.x后出现metadata generation failed之类的错误回退到23.x通常能解决。3. 陷阱二依赖库版本冲突装上了也导不进来3.1 RKNN Toolkit2的核心依赖链RKNN Toolkit2不是一个孤立的包它依赖一系列科学计算和深度学习相关的库。核心依赖包括依赖库作用常见版本要求numpy数值计算基础1.19.x - 1.23.xonnx模型格式解析1.10.x - 1.14.xonnxoptimizerONNX图优化0.2.x - 0.3.xprotobuf序列化3.19.x - 3.20.xtorchPyTorch模型支持1.10.x - 2.0.xtensorflowTF模型支持2.6.x - 2.12.x这些库之间本身就有复杂的版本约束关系。比如onnx1.14要求protobuf3.20.2而某些RKNN Toolkit2版本又要求protobuf3.20.x稍不注意就会陷入依赖地狱。3.2 最典型的冲突numpy版本过高这是我在实际安装中遇到频率最高的一个问题。现在很多教程让你直接pip install numpy默认装的是最新版比如1.26.x或2.x。但RKNN Toolkit2的某些版本在编译时链接的是numpy 1.2x的C APInumpy 2.x改了ABI导致导入rknn时底层C扩展加载失败。表现症状是pip list里能看到rknn-toolkit2但import rknn时报ImportError: numpy.core.multiarray failed to import或者直接段错误。解决方法很直接——锁定numpy版本pip install numpy1.23.51.23.5是我实测下来兼容性最好的一个版本既满足RKNN Toolkit2的要求又不会和onnx、torch产生冲突。3.3 protobuf的版本陷阱protobuf是另一个重灾区。RKNN Toolkit2在解析ONNX模型时会用到protobuf如果版本不匹配会在模型加载阶段报Descriptors cannot be created directly之类的错误。这个错误的根因是protobuf 4.x改了Python生成代码的方式而RKNN Toolkit2内部用的是protobuf 3.x生成的代码。两者不兼容。解决办法pip install protobuf3.20.3提示如果你同时装了tensorflowtensorflow 2.12以下版本通常要求protobuf在3.19到3.20之间和RKNN Toolkit2的要求正好吻合。但如果装了tensorflow 2.13它要求protobuf 4.x就会和RKNN Toolkit2冲突。这种情况下建议把tensorflow降级或者干脆在另一个环境里做TF模型转换。3.4 依赖冲突的排查手法当你怀疑是依赖冲突导致的问题时不要盲目重装先用下面这套方法定位第一步确认rknn包是否真的装上了pip show rknn-toolkit2如果这条命令没有输出说明包根本没装上问题在安装阶段不在依赖。第二步如果包装上了但导入失败用详细模式看具体报错python -c import rknn 21 | head -50重点看Traceback的最后几行通常会指出是哪个C扩展或哪个依赖出了问题。第三步用pip check检查依赖一致性pip check它会列出所有版本冲突的包比如onnx 1.15.0 requires protobuf4.21.1, but you have protobuf 3.20.3。根据输出逐个调整版本。第四步如果冲突太多建议直接重建环境按固定顺序安装pip install numpy1.23.5 pip install protobuf3.20.3 pip install onnx1.12.0 pip install onnxoptimizer0.2.7 pip install rknn-toolkit2这个顺序的核心逻辑是先装底层依赖并锁定版本再装RKNN Toolkit2让pip在安装rknn时不再去动已经锁好的依赖。4. 陷阱三安装源与wheel包选择错误根本装不上4.1 RKNN Toolkit2不在PyPI上这是很多新手不知道的一点RKNN Toolkit2没有发布在PyPI上。你在终端里敲pip install rknn-toolkit2要么报No matching distribution found要么装到一个同名的无关包。正确的获取渠道是从瑞芯微的官方资源库下载wheel包。通常这些包会放在官方GitHub仓库的release页面或者官方开发者社区的下载区。文件名一般长这样rknn_toolkit2-1.5.2-cp38-cp38-linux_x86_64.whl文件名里的信息很关键cp38表示Python 3.8linux_x86_64表示Linux x86架构你必须下载和你当前环境完全匹配的wheel包否则pip会拒绝安装。4.2 wheel包安装的正确姿势下载到本地后用绝对路径安装pip install /path/to/rknn_toolkit2-1.5.2-cp38-cp38-linux_x86_64.whl如果pip报is not a supported wheel on this platform说明wheel包的标签和你的环境不匹配。用下面这行命令查看当前环境支持的wheel标签python -c from pip._internal.utils.compatibility_tags import get_supported; print([str(t) for t in get_supported()])对比一下你的wheel文件名看看cp38和linux_x86_64是否在支持列表里。如果不匹配要么换wheel包要么换Python版本。4.3 依赖安装失败的常见原因即使wheel包选对了安装过程中也可能因为依赖下载失败而中断。常见原因有两个原因一网络问题导致pip下载依赖超时。这种情况下可以配置国内镜像源pip install /path/to/rknn_toolkit2-xxx.whl -i https://pypi.tuna.tsinghua.edu.cn/simple原因二某些依赖需要编译但系统缺少编译工具。比如onnxoptimizer在某些平台上没有预编译wheel需要从源码编译这就要求系统里有gcc、g和Python开发头文件。安装命令sudo apt-get install build-essential python3-dev注意如果你在安装过程中看到gcc: command not found或者Python.h: No such file or directory基本都是缺编译工具导致的。先把这些基础包装上再重试。4.4 安装后的验证步骤装完之后不要急着跑模型先做三步验证第一步确认包信息pip show rknn-toolkit2能看到版本号、安装路径等信息说明包已经注册到当前环境。第二步导入测试python -c from rknn.api import RKNN; print(RKNN import OK)如果输出RKNN import OK说明核心模块加载正常。第三步创建一个RKNN对象做基本功能测试from rknn.api import RKNN rknn RKNN() print(rknn) rknn.release()这三步都通过才能说明RKNN Toolkit2真正可用了。5. 常见问题速查与排查流程5.1 问题速查表报错信息可能原因解决方法No module named rknn包未安装或装到了其他Python环境确认当前Python环境用pip show检查is not a supported wheel on this platformwheel包标签与Python版本或架构不匹配下载对应cp版本和架构的wheel包numpy.core.multiarray failed to importnumpy版本过高2.x降级到numpy 1.23.5Descriptors cannot be created directlyprotobuf版本过高4.x降级到protobuf 3.20.3ImportError: libxxx.so not found系统缺少运行时库用ldd查看缺失的库并安装pip install卡在下载依赖网络问题配置国内镜像源gcc: command not found缺少编译工具安装build-essential导入时段错误Segmentation fault依赖ABI不兼容重建环境锁定依赖版本5.2 一套通用的排查流程遇到No module named rknn时按下面这个顺序排查基本能覆盖90%的情况确认Python环境which python和python --version确保你操作的环境和安装的环境是同一个。确认包是否安装pip show rknn-toolkit2没有输出就是没装上。确认wheel包匹配检查wheel文件名中的cp版本和架构标签。检查依赖冲突pip check看是否有版本冲突。单独导入测试python -c import rknn看具体报错信息。检查系统库如果报.so找不到用ldd定位缺失的库。这套流程的核心逻辑是先确认“装没装上”再确认“装对了没”最后确认“能不能用”。每一步都有明确的命令和判断标准不需要凭感觉猜。5.3 几个容易忽略的细节细节一pip和python是否对应。有时候pip命令指向的是系统Python而python命令指向的是conda环境两者不是同一个。用pip --version和python --version对比一下路径就能发现。保险的做法是用python -m pip install代替直接pip install。细节二conda环境的激活状态。如果你开了多个终端窗口可能有的窗口激活了conda环境有的没有。安装前先conda activate rknn确认提示符前面有环境名。细节三残留的旧版本。如果之前装过其他版本的RKNN Toolkit2先卸载干净pip uninstall rknn-toolkit2 pip cache purge然后再装新版本。残留的.egg-info或.dist-info目录有时会干扰新版本的导入。细节四权限问题。如果用sudo pip install装到了系统目录普通用户运行时可能找不到。建议始终在用户级环境或conda环境里安装不要用sudo。6. 个人实操体会与建议我在RK3588和RK3568上部署过好几个模型从YOLOv5到ResNet再到自训练的小网络RKNN Toolkit2的安装问题几乎每次都会遇到但每次的原因都不太一样。最开始我以为是工具链不稳定后来慢慢意识到大部分问题其实出在环境管理上——Python版本、依赖版本、wheel包版本这三个“版本”只要有一个对不上就会报No module named rknn。我现在固定下来的做法是每台机器上用一个独立的conda环境Python锁3.8.10numpy锁1.23.5protobuf锁3.20.3onnx锁1.12.0然后装对应版本的RKNN Toolkit2 wheel包。这套组合在x86 Ubuntu 20.04和22.04上都验证过比较稳。环境建好之后导出成environment.yml下次换机器直接conda env create -f environment.yml省去重复排查的时间。另外一个小技巧如果你需要在同一台机器上同时做模型转换和板端推理建议建两个环境一个装x86的RKNN Toolkit2用于转换另一个装aarch64的用于板端。不要试图在一个环境里混装架构不同装不进去的。最后说一个我踩过的坑有一次装完之后import rknn一直报段错误排查了半天发现是系统里同时存在两个numpy一个在conda环境里一个在系统目录里Python导入时加载了系统目录里的旧版本。解决办法是在conda环境里强制重装numpy并确认python -c import numpy; print(numpy.__file__)输出的路径在conda环境目录下。这个细节很隐蔽但一旦遇到按这个思路查基本能定位。