树莓派系统（Raspberry Pi OS）
最后更新于
这有帮助吗？
树莓派系统（Raspberry Pi OS）是一款免费的操作系统，基于 Debian，且针对树莓派的硬件进行了适配及优化。树莓派系统拥有 35,000 余款 Debian 软件包。对于大多数树莓派使用需求而言，我们建议使用树莓派系统。
因为树莓派系统源自 Debian，因此树莓派系统基于 Debian 内的阶段发行版本。大约每 2 年发布一次。
最新版的树莓派系统基于 。上个版本基于 。
你可在 下载树莓派系统镜像。
请始终确保你在树莓派系统上运行的软件版本是最新的。这可以使你的设备免受影响，确保你能及时收到最新补丁。
在树莓派系统中，我们推荐使用 来安装、更新和卸载软件。你可以用命令行 apt 调用 APT。
apt 会把软件源列表存放在文件 /etc/apt/sources.list 中。在安装软件之前，请运行以下命令，来 刷新（update） 位于 /etc/apt/sources.list 的本地软件源：
运行以下命令，可把所有已安装的软件包 更新（upgrade） 至最新版本：
技巧
与 Debian 不同，树莓派系统始终处于开发状态。因此，软件包的依赖关系有时会发生变更，因此你应始终使用
full-upgrade，而不要用普通的upgrade。
请定期运行这些命令，确保软件保持最新状态。在使用 apt 维持树莓派系统最新状态时，也会同时把你的 Linux 内核和固件变成最新版本——因为树莓派系统把他们以 Debian 软件包的形式进行分发。
要搜索软件包，请用 apt-cache search 搜索（search）关键字：
例如，以下是关键字“raspi”的搜索结果：
搜索结果返回了多个软件包，他们的名称或简介中均包含关键词（raspi）。
使用以下命令可查看其详细信息：
例如，假设要查询“raspi-config”这个软件包，结果如下：
可使用此命令验证维护者、版本和大小是否满足你对软件包的要求。
要在你的树莓派上安装软件包，请把软件包名传给以下命令：
apt 会显示软件包将占用的磁盘容量。输入 Y 并按 回车键 来确认安装。你可以在上述命令中添加参数 -y，跳过这个确认步骤。
要在树莓派上卸载软件包，请将软件包名传给以下命令：
技巧
要彻底抹除软件包的全部痕迹（包括配置文件），请把
remove改成purge。
apt 将显示：在卸载软件包后，可释放的磁盘容量。输入 Y，再按 回车键 确认卸载。你可以在上述命令中添加参数 -y，跳过这个确认步骤。
apt 磁盘使用情况在执行之前，sudo apt full-upgrade 将显示完成更新所需的下载及存储会占用的磁盘容量。要查看你的剩余磁盘空间是否充足，请运行以下命令：
apt 会把已下载的软件包（.deb 文件）存储到 /var/cache/apt/archives。在安装过程中，apt 会下载这些软件包，然后把文件从软件包复制到对应的安装位置。视你安装的软件而定，软件包自身可能会占用大量空间。要删除所有遗留的软件包本体，请运行以下命令：
警告
在尝试进行大版本更新前，请先行备份。
要把树莓派系统这个操作系统更新至最新大版本，请使用另外一张存储卡，在它上面写入新版本的镜像。从先前安装的旧系统（使用存储卡读卡器或网络存储）复制文件和配置到这张新的存储卡。然后，将这张新的存储卡插进树莓派上的卡槽，再启动。
警告
在尝试固件更新前，请先行备份。
警告
软件的预发布版本能否正常工作，是无法保证的。除非得到了树莓派工程师的建议，否则不要在系统上使用
rpi-update。这可能导致你的系统不稳定，甚至损坏。不要把rpi-update视为日常更新流程的一部分。
rpi-update 会下载最新的 Linux 内核预发布版本及与其匹配的内核模块、设备树文件和最新的 VideoCore 固件。然后把这些文件安装到树莓派系统中。
要进行更新，请以 root 身份执行 rpi-update。更新完成后，需重启你的树莓派以使这些变更生效：
这本白皮书记录了如何在树莓派系统中更新 VideoCore 固件。
如果你在把固件更新到最新版本后遇到问题，请使用以下命令把固件回滚到最新稳定版：
注意
如果你仍在使用树莓派操作系统 Bullseye，则必须用以下命令重装
raspberrypi-kernel：最后，用
sudo reboot重启你的树莓派以使上述变更生效。
要在树莓派桌面播放音视频文件，请在文件管理器里双击文件。这将自动触发 VLC 播放文件。或者，在菜单“声音和视频（Sound & Video）”中启动 VLC 媒体播放器（VLC Media Player）。然后，从菜单“媒体（Media）”中选择“打开文件...（Open File…）”，然后找到到要播放的文件。
在默认情况下，树莓派系统会通过 HDMI 将音频输出至你的显示器。要把音频输出到其他接口（如耳机插孔、USB 扬声器），请右键单击系统托盘中的扬声器图标，然后按需选用。
vlc 命令行你还可以用命令行启动 VLC。在下面的例子中，我们使用了来自《大雄兔》（Big Buck Bunny）的片段。要在树莓派上下载该片段，请执行以下命令：
要用命令行 VLC 播放视频，请运行以下命令：
要在文件播放完成后退出 VLC 的图形界面，请添加参数 --play-and-exit：
要全屏播放视频（在某些情况下播放会更流畅），请添加参数 --fullscreen：
cvlc 播放无图形界面的媒体如果你在以上命令中把 vlc 改成 cvlc，那么将不会显示 VLC 的图形界面：
同完整版本的树莓派系统（所有 with desktop 版本）相比，精简版树莓派系统上并未预装 VLC。要在精简版树莓派系统上使用 VLC 播放音视频，请安装用于无需桌面播放的软件包：
为了下面的示例，我们使用了一个短音频的片段剪辑。要在树莓派上下载该片段，请执行以下命令：
要在命令行让 VLC 播放片段，请执行以下命令：
用以下参数来替换占位符 <alsa-设备> ：
sysdefault:CARD=Headphones
耳机插孔
sysdefault:CARD=vc4hdmi
树莓派 Zero，树莓派 1、2、3 上的 HDMI 输出
sysdefault:CARD=vc4hdmi0
树莓派 4、5、400 和计算模块 4 上的 HDMI0 输出
sysdefault:CARD=vc4hdmi1
树莓派 4、5、400 和计算模块 4 上的 HDMI1 输出
技巧
使用以下命令，可获取树莓派上所有 ALSA 设备列表：
为了把视频强制输出到特定设备，即指定视频输出设备，请使用参数 --drm-vout-display：
请把其中的文本 <drm设备> 改成以下某设备：
HDMI-A-1
树莓派 Zero、1、2、3 上的 HDMI 输出；树莓派 4、5、400 上的 HDMI0 输出
HDMI-A-2
树莓派 4、5、400 上的 HDMI1 输出
DSI-1
树莓派触摸显示屏
技巧
使用以下命令，可获取树莓派上所有 DRM 设备列表：
你可以对音频和视频输出参数进行组合。例如，要把视频定向输出到触摸屏，而把音频定向输出到耳机插孔，根据上述需求，应执行的命令组合为：
如果你有 H.264 原始码流（裸流，raw H.264 stream），比如用树莓派摄像头模块捕获的码流，你可以通过把码流封装成诸如 MP4 之类的文件格式，来提升 VLC 的播放性能。你可以使用 ffmpeg 把码流内容转成容器文件。例如，以下命令可把名为 video.h264 的码流，转成 MP4 文件 video.mp4（30fps）：
树莓派系统中预装了几款实用的命令行工具。
kmsprintvclogvclog 能运行在基于 Arm 的 Linux 上，可输出 VideoCore GPU 的日志消息。它需要以 root 权限执行。
sudo vclog --msg 可打印出消息日志，而 sudo vclog --assert 则打印出断言日志。
vcgencmd要获取 vcgencmd 支持的所有命令列表，请使用 vcgencmd commands。下面列出了一些实用命令及其所需参数。
vcos命令 vcos 有两个有用的子命令：
version 可显示 VideoCore 固件的构建日期和版本
log status 可显示 VideoCore 固件所有部分的错误日志状态
version可显示 VideoCore 固件的构建日期和版本。
get_throttled将返回系统的限流状态，为位模式。设置位表示以下含义：
0
0x1
已检测到欠压
1
0x2
Arm 频率已受限
2
0x4
当前已被限流
3
0x8
已启用温度软限制
16
0x10000
曾发生欠压
17
0x20000
曾发生 Arm 频率限制
18
0x40000
曾发生限流
19
0x80000
曾发生温度软限制
measure_tempmeasure_temp 可返回 SoC 的温度，数据源于其内部温度传感器。在树莓派 4 上，measure_temp pmic 返回的温度来自电源管理芯片（PMIC）。
measure_clock [时钟]它将返回指定时钟的实时频率。可返回以下时钟值：
arm
ARM 核心
core
GPU 核心
h264
H.264 模块
isp
图像传感器管道
v3d
3D 模块
uart
串口
pwm
PWM 模块（模拟音频输出）
emmc
存储卡接口
pixel
像素阀（Pixel valves）
vec
模拟视频编码器
hdmi
HDMI
dpi
显示并行接口
例如 vcgencmd measure_clock arm
measure_volts [模块]它可显示特定模块使用的当前电压。可接受以下值：
core
VC4 核心电压
sdram_c
SDRAM 核心电压
sdram_i
SDRAM I/O 电压
sdram_p
SDRAM 物理电压
otp_dumpget_config [配置项目|int|str]它将显示指定配置项目的值。或者如要查看给定类型的所有配置项目，可指定参数 int（整数）、str（字符串）。例如，以下命令会返回设备上的全部内存大小（单位为 Mb）：
get_mem 类型codec_enabled [类型]
可报告是否已启用指定类型的解码器。可支持以下类型：AGIF、FLAC、H263、H264、MJPA、MJPB、MJPG、MPG2、MPG4、MVC0、PCM、THRA、VORB、VP6、VP8、WMV9、WVC1。请注意，由于在树莓派 4、400 上的 H.265 硬件模块并不属于 VideoCore GPU，因此无法用此命令查看状态。
mem_oom
将显示在 VideoCore 内存空间中发生过的所有 OOM（Out of memory，内存溢出）事件的统计信息。
mem_reloc_stats
将显示来自 VideoCore 上可重定位内存分配器的统计信息。
read_ring_osc
用于返回环形振荡器的实时速度、电压和温度。
视障用户能在树莓派系统菜单中“推荐软件（Recommended Software）”找到有用的工具。
你可以从树莓派主菜单的 推荐软件（Recommended Software） 处安装 Orca 屏幕阅读器。或者，按 Ctrl + Alt + 空格键 自动安装 Orca。
在安装新系统后，首次启动树莓派系统时，将在 30 秒时播放自动语音提醒。此提醒提供了有关如何安装 Orca 的说明。
树莓派系统预装了 Python 3。对预装的系统级 Python 进行破坏，可能会引发操作系统故障。在安装第三方 Python 库时，请确保正确使用软件包管理工具。
在 Linux 上，你可以用两种方式来安装 python 依赖包：
使用 apt 来安装预配置系统软件包
在 虚拟环境中，使用 pip，即使用 Python 的依赖管理器安装库
重要
apt 安装 Python 软件包用 apt 安装的软件包，是专为树莓派系统打包的。这些软件包大都是预编译的，因此安装速度更快。由于 apt 管理能所有软件包的依赖关系，使用此方法，会同时安装运行软件包所需的所有子依赖包。而 apt 能确保你在卸载时免于对其他软件包造成破坏。
pip 安装 Python 库pip 安装的变更在旧版本的树莓派系统中，你可以用 pip 直接把库安装到系统级 Python 中。自树莓派系统 Bookworm 以降，用户无法直接把库安装到系统级 Python。
若尝试在系统级安装 Python 软件包，将会输出类似以下报错：
长期以来，Python 用户一直承受着操作系统软件包管理器（apt）和 Python 特定软件包管理工具（pip）之间的冲突。这些冲突包括 Python 的 API 不兼容性、文件所有权。
从树莓派系统 Bookworm 开始，用 pip 安装的软件包，只能安装到 Python 虚拟环境（venv）里面。虚拟环境是个容器，在这儿，你能安全地安装第三方模块，不会干扰系统级 Python。
要使用虚拟环境，请创建容器来存储环境。根据你使用 Python 的打算，有多种方法可以做到这一点。
运行以下命令可创建一个虚拟环境配置文件夹，把 <环境名> 改成你想要的虚拟环境名称（如 env）:
技巧
要在虚拟环境中，将当前已安装的系统级 Python，所有软件包所在的文件夹，预加载至虚拟环境，请使用参数
--system-site-packages。
然后，在虚拟环境配置文件夹中执行命令 bin/activate 以进入虚拟环境：
然后，你应该会看到类似如下提示，其内容为：
命令提示符前缀 (<环境名>) 代表当前终端会话位于名为 <环境名> 的虚拟环境中。
要查看当前是否位于虚拟环境，请使用 pip list，查看已安装软件包的列表：
虚拟环境中已安装的输出列表应该要比系统级的 Python 要短得多。你现在可以放心地使用 pip 来安装软件包了。在虚拟环境中，使用 pip 安装的所有软件包都只会安装到这个虚拟环境中。在虚拟环境中，命令 python 和 python3 会自动调用虚拟环境中的 Python 版本和已安装的软件包，而非系统级 Python。
要退出虚拟环境，请运行以下命令：
许多用户会为每个 Python 项目都创建一个单独的虚拟环境。然后将虚拟环境放置在每个项目的根目录中（通常使用名称 env）。在每个项目的根目录下，运行以下命令可创建虚拟环境配置文件夹。
在开始你的项目工作之前，请在项目根目录下运行以下命令，以开始使用虚拟环境：
然后，你应该会看到类似提示如下，内容为：
当你完成项目工作后，可在任意目录下运行命令，来退出虚拟环境：
与为每个 Python 项目都创建一个虚拟环境有所不同，你可以为你的用户账户，单独创建一个虚拟环境。在运行其他 Python 程序之前，先激活这个虚拟环境。 这种方法对于在项目之间共享许多库的工作流可能更方便。
使用以下命令，在当前用户的主目录中，隐藏文件夹下，创建虚拟环境：
在其他目录，运行命令，即可开始使用虚拟环境：
然后你应该会看到类似如下提示信息：
在任意目录，运行以下命令即可退出虚拟环境：
在默认情况下，Thonny 会使用系统级 Python。但是，你可以通过单击 Thonny 窗口右下角的 解释器菜单（interpreter menu） 切换使用 Python 虚拟环境。可选择配置好的环境，或使用 配置解释器（Configure interpreter…） 来配置一个新的虚拟环境。
以下示例代码用于控制接入到 GPIO17 的 LED：
可在类似 Thonny 的 IDE 中运行，LED 会不停地闪烁。
LED 方法包括 on()、off()、toggle() 和 blink()。
以下示例代码，可读取接入到 GPIO2 按钮的状态：
按钮函数包括属性 is_pressed 和 is_held；回调 when_pressed、when_released 和 when_held；以及方法 wait_for_press() 和 wait_for_release。
以下示例代码可读取接入 GPIO2 的按钮状态，并在按下按钮时，点亮接入到 GPIO17 的 LED：
还可这么写：
亦或这么写：
在树莓派官方发布了树莓派系统的大版本更新后，执行上述命令亦不会把你的操作系统更新到这个最新的大版本。要更新到最新的大版本，请按照我们的进行操作。
要把你树莓派的固件更至最新版本，请使用 。
rpi-update 使用的所有源数据均来自 。该存储库包含来自的数据子集。
树莓派系统预装了 。你可以它播放音视频文件。在树莓派系统上，VLC 支持硬件加速，可兼容多种常见的音视频文件格式。
要把音频强制输出到特定设备，请使用 音频输出：把 alsa 值传给参数 -A。同时使用参数 --alsa-audio-device 来指定音频输出设备：
工具 kmsprint 能列出已接入树莓派的显示器所支持的分辨率。使用 kmsprint 可查看已接入树莓派的显示器的详细信息，使用 kmsprint -m 能查看显示器支持的所有分辨率列表。你可以在 找到实用程序 kmsprint 的源代码。
vcgencmd 工具用于输出树莓派上有关 VideoCore GPU 的信息。你可以在 找到工具 vcgencmd 的源代码。
它将显示 SoC 内部 OTP（一次性可编程，one-time programmable）存储器中的内容。这些是 32 位值，索引范围是 8 到 64。有关更多详细信息，请参阅 。
get_mem 类型 将报告 Arm 和 GPU 可寻址内存的大小。要显示 Arm 可寻址内存的大小，请使用 vcgencmd get_mem arm；要显示 GPU 可寻址内存的数量，请使用 vcgencmd get_mem gpu。若设备内存大于 1GB，arm 参数的返回值将始终用 1GB 减 gpu 显存，因为 GPU 固件仅获取前 1GB 内存。要想准确报告设备上的总内存，请参阅 total_mem 配置项和上述 部分。
我们还提供了 来简化树莓派桌面的访问。此外，我们还提供了屏幕放大器来放大用户界面，提高屏幕内容的可读性。
自树莓派系统 Bookworm 以降，若使用 pip，你只能将其安装至 Python 虚拟环境（venv）。该变更是由 Python 社区引入的，与树莓派无关：有关更多信息，请参阅 。
例如，要安装使用树莓派 的 Python 3 库，请运行以下命令：
要查找使用 apt 分发的 Python 包，请。在大多数情况下，Python 包使用前缀 python- 和 python3-：比如，你会发现，名为 python3-numpy 的包，即为 numpy。
应该。要为所有用户把库安装为系统级，。
当为整个用户账户，跨多个项目创建虚拟环境时，可考虑将虚拟环境配置文件放在你的主目录下。可将其配置存储在，以便在默认情况下，隐藏该文件夹，防止在主目录里弄混。
我们推荐使用 ，来编辑树莓派上的 Python 代码。
使用 库能轻松地控制 GPIO 设备。该库在 上有全面的文档。
关于 GPIO 硬件的信息，请参见 。
你可以在由树莓派出版社出版的书籍中，找到有关如何使用 GPIO Zero Python 库编程，联系你树莓派的更多信息。该书使用 GPIO Zero 库帮助你入门，并通过构建一系列项目来指导你如何使用它。
你可以免费的 PDF 文件，它是根据发布的。
