树莓派系统（Raspberry Pi OS）

简介

树莓派系统（Raspberry Pi OS）是一款免费的操作系统，基于 Debian，且针对树莓派的硬件进行了适配及优化。树莓派系统拥有 35,000 余款 Debian 软件包。对于大多数树莓派使用需求而言，我们建议使用树莓派系统。

因为树莓派系统源自 Debian，因此树莓派系统基于 Debian 发布周期内的阶段发行版本。大约每 2 年发布一次。

最新版的树莓派系统基于 Debian Bookworm。上个版本基于 Debian Bullseye。

你可在 raspberrypi.com/software/operating-systems/ 下载树莓派系统镜像。

更新软件

请始终确保你在树莓派系统上运行的软件版本是最新的。这可以使你的设备免受漏洞影响，确保你能及时收到最新补丁。

使用 APT 管理软件包

在树莓派系统中，我们推荐使用 APT（Advanced Package Tool，高级软件包工具）来安装、更新和卸载软件。你可以用命令行 apt 调用 APT。

安装更新

apt 会把软件源列表存放在文件 /etc/apt/sources.list 中。在安装软件之前，请运行以下命令，来 刷新（update） 位于 /etc/apt/sources.list 的本地软件源：

$ sudo apt update

运行以下命令，可把所有已安装的软件包 更新（upgrade） 至最新版本：

$ sudo apt full-upgrade

技巧
与 Debian 不同，树莓派系统始终处于开发状态。因此，软件包的依赖关系有时会发生变更，因此你应始终使用 full-upgrade，而不要用普通的 upgrade。

请定期运行这些命令，确保软件保持最新状态。在使用 apt 维持树莓派系统最新状态时，也会同时把你的 Linux 内核和固件变成最新版本——因为树莓派系统把他们以 Debian 软件包的形式进行分发。

在树莓派官方发布了树莓派系统的大版本更新后，执行上述命令亦不会把你的操作系统更新到这个最新的大版本。要更新到最新的大版本，请按照我们的操作系统更新说明进行操作。

搜索软件

要搜索软件包，请用 apt-cache search 搜索（search）关键字：

$ apt-cache search <关键字>

例如，以下是关键字“raspi”的搜索结果：

$ apt-cache search raspi
raspi3-firmware - Raspberry Pi 2 and 3 GPU firmware and bootloaders
libcamera-apps - libcamera-apps
libcamera-apps-lite - libcamera-apps-lite
python-picamera - Pure Python interface to the Raspberry Pi's camera module.
python-picamera-docs - Documentation for the Python interface to the RPi's camera module.
python3-picamera - Pure Python interface to the Raspberry Pi's camera module.
raspi-config - Raspberry Pi configuration tool
raspi-gpio - Dump the state of the BCM270x GPIOs
raspi-gpio-dbgsym - debug symbols for raspi-gpio
raspinfo - Dump information about the Pi
rc-gui - raspi-config GUI
raspi-copies-and-fills - ARM-accelerated versions of selected functions from string.h
raspi-copies-and-fills-dbgsym - debug symbols for raspi-copies-and-fills

搜索结果返回了多个软件包，他们的名称或简介中均包含关键词（raspi）。

使用以下命令可查看其详细信息：

$ apt-cache show <软件包名>

例如，假设要查询“raspi-config”这个软件包，结果如下：

$ apt-cache show raspi-config
Package: raspi-config
Version: 20210212
Architecture: all
Maintainer: Serge Schneider <serge@raspberrypi.org>
Installed-Size: 121
Depends: whiptail, parted, lua5.1, alsa-utils, psmisc, initramfs-tools
Recommends: triggerhappy, iw
Priority: optional
Section: utils
Filename: pool/main/r/raspi-config/raspi-config_20210212_all.deb
Size: 27976
SHA256: 772d4fd3c6d8c9da47ac56012b74e7828b53c8521ff1c47266bb38ec71750c10
SHA1: 08254c976a8260bde914c2df72f92ffb9317fef6
MD5sum: 80aaac13be6a9b455c822edb91cf8ea2
Description: Raspberry Pi configuration tool
 A simple configuration tool for common Raspberry Pi administrative tasks
Description-md5: 19630c04463bfe7193152448b53d85a0

可使用此命令验证维护者、版本和大小是否满足你对软件包的要求。

安装软件包

要在你的树莓派上安装软件包，请把软件包名传给以下命令：

$ sudo apt install <软件包名>

apt 会显示软件包将占用的磁盘容量。输入 Y 并按 回车键 来确认安装。你可以在上述命令中添加参数 -y，跳过这个确认步骤。

卸载软件包

要在树莓派上卸载软件包，请将软件包名传给以下命令：

$ sudo apt remove <软件包名>

技巧
要彻底抹除软件包的全部痕迹（包括配置文件），请把 remove 改成 purge。

apt 将显示：在卸载软件包后，可释放的磁盘容量。输入 Y，再按 回车键 确认卸载。你可以在上述命令中添加参数 -y，跳过这个确认步骤。

管理 `apt` 磁盘使用情况

在执行之前，sudo apt full-upgrade 将显示完成更新所需的下载及存储会占用的磁盘容量。要查看你的剩余磁盘空间是否充足，请运行以下命令：

$ df -h

apt 会把已下载的软件包（.deb 文件）存储到 /var/cache/apt/archives。在安装过程中，apt 会下载这些软件包，然后把文件从软件包复制到对应的安装位置。视你安装的软件而定，软件包自身可能会占用大量空间。要删除所有遗留的软件包本体，请运行以下命令：

$ sudo apt clean

把你的操作系统更新至最新大版本（major version）

警告
在尝试进行大版本更新前，请先行备份。

要把树莓派系统这个操作系统更新至最新大版本，请使用另外一张存储卡，在它上面写入新版本的镜像。从先前安装的旧系统（使用存储卡读卡器或网络存储）复制文件和配置到这张新的存储卡。然后，将这张新的存储卡插进树莓派上的卡槽，再启动。

更新你的固件

警告
在尝试固件更新前，请先行备份。

警告
软件的预发布版本能否正常工作，是无法保证的。除非得到了树莓派工程师的建议，否则不要在系统上使用 rpi-update。这可能导致你的系统不稳定，甚至损坏。不要把 rpi-update 视为日常更新流程的一部分。

要把你树莓派的固件更至最新版本，请使用 rpi-update。

rpi-update 会下载最新的 Linux 内核预发布版本及与其匹配的内核模块、设备树文件和最新的 VideoCore 固件。然后把这些文件安装到树莓派系统中。

rpi-update 使用的所有源数据均来自 rpi-firmware 存储库。该存储库包含来自官方固件存储库的数据子集。

要进行更新，请以 root 身份执行 rpi-update。更新完成后，需重启你的树莓派以使这些变更生效：

$ sudo rpi-update
$ sudo reboot

白皮书

树莓派固件更新白皮书
这本白皮书记录了如何在树莓派系统中更新 VideoCore 固件。

把固件降级到最新稳定版本

如果你在把固件更新到最新版本后遇到问题，请使用以下命令把固件回滚到最新稳定版：

$ sudo apt-get update
$ sudo apt install --reinstall raspi-firmware

注意
如果你仍在使用树莓派操作系统 Bullseye，则必须用以下命令重装 raspberrypi-kernel：
$ sudo apt install --reinstall libraspberrypi0 libraspberrypi-{bin,dev,doc} raspberrypi-{kernel,bootloader}
最后，用 sudo reboot 重启你的树莓派以使上述变更生效。

播放音视频

树莓派系统预装了 VLC 媒体播放器。你可以它播放音视频文件。在树莓派系统上，VLC 支持硬件加速，可兼容多种常见的音视频文件格式。

VLC 媒体播放器

图形界面的 VLC

要在树莓派桌面播放音视频文件，请在文件管理器里双击文件。这将自动触发 VLC 播放文件。或者，在菜单“声音和视频（Sound & Video）”中启动 VLC 媒体播放器（VLC Media Player）。然后，从菜单“媒体（Media）”中选择“打开文件...（Open File…）”，然后找到到要播放的文件。

在默认情况下，树莓派系统会通过 HDMI 将音频输出至你的显示器。要把音频输出到其他接口（如耳机插孔、USB 扬声器），请右键单击系统托盘中的扬声器图标，然后按需选用。

`vlc` 命令行

你还可以用命令行启动 VLC。在下面的例子中，我们使用了来自《大雄兔》（Big Buck Bunny）的片段。要在树莓派上下载该片段，请执行以下命令：

$ wget --trust-server-names http://rptl.io/big-buck-bunny

要用命令行 VLC 播放视频，请运行以下命令：

$ vlc big-buck-bunny-1080p.mp4

要在文件播放完成后退出 VLC 的图形界面，请添加参数 --play-and-exit：

$ vlc --play-and-exit big-buck-bunny-1080p.mp4

要全屏播放视频（在某些情况下播放会更流畅），请添加参数 --fullscreen：

$ vlc --play-and-exit --fullscreen big-buck-bunny-1080p.mp4

使用 `cvlc` 播放无图形界面的媒体

如果你在以上命令中把 vlc 改成 cvlc，那么将不会显示 VLC 的图形界面：

$ cvlc --play-and-exit big-buck-bunny-1080p.mp4

在精简版树莓派系统上播放音视频

同完整版本的树莓派系统（所有 with desktop 版本）相比，精简版树莓派系统上并未预装 VLC。要在精简版树莓派系统上使用 VLC 播放音视频，请安装用于无需桌面播放的软件包：

$ sudo apt install --no-install-recommends vlc-bin vlc-plugin-base

为了下面的示例，我们使用了一个短音频的片段剪辑。要在树莓派上下载该片段，请执行以下命令：

$ wget --trust-server-names http://rptl.io/startup-music

要在命令行让 VLC 播放片段，请执行以下命令：

$ cvlc --play-and-exit computer-startup-music.mp3

指定音频输出设备

要把音频强制输出到特定设备，请使用 ALSA 音频输出：把 alsa 值传给参数 -A。同时使用参数 --alsa-audio-device 来指定音频输出设备：

$ cvlc --play-and-exit -A alsa --alsa-audio-device <alsa-设备> computer-startup-music.mp3

用以下参数来替换占位符 <alsa-设备> ：

ALSA 设备

说明

技巧
使用以下命令，可获取树莓派上所有 ALSA 设备列表：
$ aplay -L | grep sysdefault

指定视频输出设备

为了把视频强制输出到特定设备，即指定视频输出设备，请使用参数 --drm-vout-display：

$ cvlc --play-and-exit --drm-vout-display <drm设备> big-buck-bunny-1080p.mp4

请把其中的文本 <drm设备> 改成以下某设备：

DRM 设备

说明

技巧
使用以下命令，可获取树莓派上所有 DRM 设备列表：
$ kmsprint | grep Connector

指定音视频输出设备

你可以对音频和视频输出参数进行组合。例如，要把视频定向输出到触摸屏，而把音频定向输出到耳机插孔，根据上述需求，应执行的命令组合为：

$ cvlc --play-and-exit --fullscreen --drm-vout-display DSI-1 -A alsa --alsa-audio-device sysdefault:CARD=Headphones your_video.mp4

改善流媒体播放性能

如果你有 H.264 原始码流（裸流，raw H.264 stream），比如用树莓派摄像头模块捕获的码流，你可以通过把码流封装成诸如 MP4 之类的文件格式，来提升 VLC 的播放性能。你可以使用 ffmpeg 把码流内容转成容器文件。例如，以下命令可把名为 video.h264 的码流，转成 MP4 文件 video.mp4（30fps）：

$ ffmpeg -r 30 -i video.h264 -c:v copy video.mp4

实用工具

树莓派系统中预装了几款实用的命令行工具。

`kmsprint`

工具 kmsprint 能列出已接入树莓派的显示器所支持的分辨率。使用 kmsprint 可查看已接入树莓派的显示器的详细信息，使用 kmsprint -m 能查看显示器支持的所有分辨率列表。你可以在 Github 上找到实用程序 kmsprint 的源代码。

`vclog`

vclog 能运行在基于 Arm 的 Linux 上，可输出 VideoCore GPU 的日志消息。它需要以 root 权限执行。

sudo vclog --msg 可打印出消息日志，而 sudo vclog --assert 则打印出断言日志。

`vcgencmd`

vcgencmd 工具用于输出树莓派上有关 VideoCore GPU 的信息。你可以在 GitHub 上找到工具 vcgencmd 的源代码。

要获取 vcgencmd 支持的所有命令列表，请使用 vcgencmd commands。下面列出了一些实用命令及其所需参数。

`vcos`

命令 vcos 有两个有用的子命令：

version 可显示 VideoCore 固件的构建日期和版本
log status 可显示 VideoCore 固件所有部分的错误日志状态

`version`

可显示 VideoCore 固件的构建日期和版本。

`get_throttled`

将返回系统的限流状态，为位模式。设置位表示以下含义：

位

十六进制（Hex）值

意义

`measure_temp`

measure_temp 可返回 SoC 的温度，数据源于其内部温度传感器。在树莓派 4 上，measure_temp pmic 返回的温度来自电源管理芯片（PMIC）。

`measure_clock [时钟]`

它将返回指定时钟的实时频率。可返回以下时钟值：

时钟

说明

例如 vcgencmd measure_clock arm

`measure_volts [模块]`

它可显示特定模块使用的当前电压。可接受以下值：

模块

说明

`otp_dump`

它将显示 SoC 内部 OTP（一次性可编程，one-time programmable）存储器中的内容。这些是 32 位值，索引范围是 8 到 64。有关更多详细信息，请参阅 OTP 位页面。

`get_config [配置项目|int|str]`

它将显示指定配置项目的值。或者如要查看给定类型的所有配置项目，可指定参数 int（整数）、str（字符串）。例如，以下命令会返回设备上的全部内存大小（单位为 Mb）：

$ vcgencmd get_config total_mem

`get_mem 类型`

get_mem 类型 将报告 Arm 和 GPU 可寻址内存的大小。要显示 Arm 可寻址内存的大小，请使用 vcgencmd get_mem arm；要显示 GPU 可寻址内存的数量，请使用 vcgencmd get_mem gpu。若设备内存大于 1GB，arm 参数的返回值将始终用 1GB 减 gpu 显存，因为 GPU 固件仅获取前 1GB 内存。要想准确报告设备上的总内存，请参阅 total_mem 配置项和上述 get_config 部分。

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）”找到有用的工具。

我们还提供了 Orca 屏幕阅读器来简化树莓派桌面的访问。此外，我们还提供了屏幕放大器来放大用户界面，提高屏幕内容的可读性。

Orca 屏幕阅读器

你可以从树莓派主菜单的 推荐软件（Recommended Software） 处安装 Orca 屏幕阅读器。或者，按 Ctrl + Alt + 空格键 自动安装 Orca。

在安装新系统后，首次启动树莓派系统时，将在 30 秒时播放自动语音提醒。此提醒提供了有关如何安装 Orca 的说明。

在树莓派上使用 Python

树莓派系统预装了 Python 3。对预装的系统级 Python 进行破坏，可能会引发操作系统故障。在安装第三方 Python 库时，请确保正确使用软件包管理工具。

在 Linux 上，你可以用两种方式来安装 python 依赖包：

使用 apt 来安装预配置系统软件包
在 虚拟环境中，使用 pip，即使用 Python 的依赖管理器安装库

重要
自树莓派系统 Bookworm 以降，若使用 pip，你只能将其安装至 Python 虚拟环境（venv）。该变更是由 Python 社区引入的，与树莓派无关：有关更多信息，请参阅 PEP 668。

使用 `apt` 安装 Python 软件包

用 apt 安装的软件包，是专为树莓派系统打包的。这些软件包大都是预编译的，因此安装速度更快。由于 apt 管理能所有软件包的依赖关系，使用此方法，会同时安装运行软件包所需的所有子依赖包。而 apt 能确保你在卸载时免于对其他软件包造成破坏。

例如，要安装使用树莓派 Build 扩展板的 Python 3 库，请运行以下命令：

$ sudo apt install python3-build-hat

要查找使用 apt 分发的 Python 包，请使用 apt search。在大多数情况下，Python 包使用前缀 python- 和 python3-：比如，你会发现，名为 python3-numpy 的包，即为 numpy。

使用 `pip` 安装 Python 库

Bookworm 上 `pip` 安装的变更

在旧版本的树莓派系统中，你可以用 pip 直接把库安装到系统级 Python 中。自树莓派系统 Bookworm 以降，用户无法直接把库安装到系统级 Python。

应该把库安装到虚拟环境（venv）。要为所有用户把库安装为系统级，请用 apt 来安装。

若尝试在系统级安装 Python 软件包，将会输出类似以下报错：

$ pip install buildhat
error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
  python3-xyz, where xyz is the package you are trying to
  install.

  If you wish to install a non-Debian-packaged Python package,
  create a virtual environment using python3 -m venv path/to/venv.
  Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
  sure you have python3-full installed.

  For more information visit http://rptl.io/venv

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

长期以来，Python 用户一直承受着操作系统软件包管理器（apt）和 Python 特定软件包管理工具（pip）之间的冲突。这些冲突包括 Python 的 API 不兼容性、文件所有权。

从树莓派系统 Bookworm 开始，用 pip 安装的软件包，只能安装到 Python 虚拟环境（venv）里面。虚拟环境是个容器，在这儿，你能安全地安装第三方模块，不会干扰系统级 Python。

使用 pip 和虚拟环境

要使用虚拟环境，请创建容器来存储环境。根据你使用 Python 的打算，有多种方法可以做到这一点。

运行以下命令可创建一个虚拟环境配置文件夹，把 <环境名> 改成你想要的虚拟环境名称（如 env）:

$ python -m venv <环境名>

技巧
要在虚拟环境中，将当前已安装的系统级 Python，所有软件包所在的文件夹，预加载至虚拟环境，请使用参数 --system-site-packages。

然后，在虚拟环境配置文件夹中执行命令 bin/activate 以进入虚拟环境：

$ source <环境名>/bin/activate

然后，你应该会看到类似如下提示，其内容为：

(<环境名>) $

命令提示符前缀 (<环境名>) 代表当前终端会话位于名为 <环境名> 的虚拟环境中。

要查看当前是否位于虚拟环境，请使用 pip list，查看已安装软件包的列表：

(<环境名>) $ pip list
Package    Version
---------- -------
pip        23.0.1
setuptools 66.1.1

虚拟环境中已安装的输出列表应该要比系统级的 Python 要短得多。你现在可以放心地使用 pip 来安装软件包了。在虚拟环境中，使用 pip 安装的所有软件包都只会安装到这个虚拟环境中。在虚拟环境中，命令 python 和 python3 会自动调用虚拟环境中的 Python 版本和已安装的软件包，而非系统级 Python。

要退出虚拟环境，请运行以下命令：

(<环境名>) $ deactivate

为每个项目使用独立的环境

许多用户会为每个 Python 项目都创建一个单独的虚拟环境。然后将虚拟环境放置在每个项目的根目录中（通常使用名称 env）。在每个项目的根目录下，运行以下命令可创建虚拟环境配置文件夹。

$ python -m venv env

在开始你的项目工作之前，请在项目根目录下运行以下命令，以开始使用虚拟环境：

$ source env/bin/activate

然后，你应该会看到类似提示如下，内容为：

(env) $

当你完成项目工作后，可在任意目录下运行命令，来退出虚拟环境：

(env) $ deactivate

为每个用户使用独立的环境

与为每个 Python 项目都创建一个虚拟环境有所不同，你可以为你的用户账户，单独创建一个虚拟环境。在运行其他 Python 程序之前，先激活这个虚拟环境。 这种方法对于在项目之间共享许多库的工作流可能更方便。

当为整个用户账户，跨多个项目创建虚拟环境时，可考虑将虚拟环境配置文件放在你的主目录下。可将其配置存储在一个以点开头的文件夹中，以便在默认情况下，隐藏该文件夹，防止在主目录里弄混。

使用以下命令，在当前用户的主目录中，隐藏文件夹下，创建虚拟环境：

$ python -m venv ~/.env

在其他目录，运行命令，即可开始使用虚拟环境：

$ source ~/.env/bin/activate

然后你应该会看到类似如下提示信息：

(.env) $

在任意目录，运行以下命令即可退出虚拟环境：

(.env) $ deactivate

使用 Thonny 编辑器

我们推荐使用 Thonny，来编辑树莓派上的 Python 代码。

在默认情况下，Thonny 会使用系统级 Python。但是，你可以通过单击 Thonny 窗口右下角的 解释器菜单（interpreter menu） 切换使用 Python 虚拟环境。可选择配置好的环境，或使用 配置解释器（Configure interpreter…） 来配置一个新的虚拟环境。

用 Python 控制 GPIO

使用 GPIO Zero 库能轻松地控制 GPIO 设备。该库在 gpiozero.readthedocs.io 上有全面的文档。

关于 GPIO 硬件的信息，请参见 GPIO 硬件。

控制 LED

以下示例代码用于控制接入到 GPIO17 的 LED：

from gpiozero import LED
from time import sleep

led = LED(17)

while True:
    led.on()
    sleep(1)
    led.off()
    sleep(1)

可在类似 Thonny 的 IDE 中运行，LED 会不停地闪烁。

LED 方法包括 on()、off()、toggle() 和 blink()。

读取按钮状态

以下示例代码，可读取接入到 GPIO2 按钮的状态：

from gpiozero import Button
from time import sleep

button = Button(2)

while True:
    if button.is_pressed:
        print("Pressed")
    else:
        print("Released")
    sleep(1)

按钮函数包括属性 is_pressed 和 is_held；回调 when_pressed、when_released 和 when_held；以及方法 wait_for_press() 和 wait_for_release。

用按钮控制 LED

以下示例代码可读取接入 GPIO2 的按钮状态，并在按下按钮时，点亮接入到 GPIO17 的 LED：

from gpiozero import LED, Button

led = LED(17)
button = Button(2)

while True:
    if button.is_pressed:
        led.on()
    else:
        led.off()

还可这么写：

from gpiozero import LED, Button

led = LED(17)
button = Button(2)

while True:
    button.wait_for_press()
    led.on()
    button.wait_for_release()
    led.off()

亦或这么写：

from gpiozero import LED, Button

led = LED(17)
button = Button(2)

button.when_pressed = led.on
button.when_released = led.off

进一步阅读

你可以在由树莓派出版社出版的书籍《GPIO Zero 基础电子学》（Simple Electronics with GPIO Zero）中，找到有关如何使用 GPIO Zero Python 库编程，联系你树莓派的更多信息。该书使用 GPIO Zero 库帮助你入门，并通过构建一系列项目来指导你如何使用它。

你可以免费下载这本书的 PDF 文件，它是根据知识共享署名-非商业性使用-相同方式共享 3.0 国际许可（CC BY NC-SA）发布的。

最后更新于2个月前

简介