# Source: updating.adoc

*Note: This file could not be automatically converted from AsciiDoc.*

== Update software

Always keep the software running on your Raspberry Pi updated to the latest version. This keeps your device secure from https://cve.mitre.org/index.html[vulnerabilities] and ensures that you get the latest bug fixes.

=== Manage software packages with APT

https://en.wikipedia.org/wiki/APT_(software)[Advanced Package Tool (APT)] is the recommended way to install, update, and remove software in Raspberry Pi OS. You can access APT through the `apt` CLI.

==== Install updates

`apt` stores a list of software sources in a file at `/etc/apt/sources.list`. Before installing software, run the following command to *update* your local list of packages using `/etc/apt/sources.list`:

[source,console]
----
$ sudo apt update
----

Run the following command to *upgrade* all your installed packages to their latest versions:

[source,console]
----
$ sudo apt full-upgrade
----

TIP: Unlike Debian, Raspberry Pi OS is under continual development. As a result, package dependencies sometimes change, so you should always use `full-upgrade` instead of the standard `upgrade`.

Run these commands regularly to keep your software up-to-date. Using `apt` to keep Raspberry Pi OS up to date also keeps your Linux kernel and firmware up to date, since Raspberry Pi distributes them as Debian packages.

When Raspberry Pi releases a new major version of Raspberry Pi OS, the above commands won't upgrade your operating system to that new major version. To upgrade to a new major version, follow our xref:os.adoc#upgrade-your-operating-system-to-a-new-major-version[OS upgrade instructions].

==== Search for software

To search the archives for a package, pass a search keyword to `apt-cache search`:

[source,console]
----
$ apt-cache search <keyword>
----

For example, consider the following search for the keyword "raspi":

[source,console]
----
$ 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
----

The search returned multiple packages with names or descriptions that included the keyword.

Use the following command to view detailed information about a package:

[source,console]
----
$ apt-cache show <package-name>
----

For example, consider the following query for the "raspi-config" package:

[source,console]
----
$ 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
----

Use this command to verify that the maintainer, version, and size match your expectations for a package.

==== Install a package

To install a package on your Raspberry Pi, pass the name of the package to the following command:

[source,console]
----
$ sudo apt install <package-name>
----

`apt` will display the amount of disk space the package will consume. Enter *Y* and press **Enter** to confirm installation of the package. You can skip this confirmation step by adding the `-y` flag to the command above.

==== Uninstall a package

To uninstall a package from your Raspberry Pi, pass the name of the package to the following command:

[source,console]
----
$ sudo apt remove <package-name>
----

TIP: To completely remove all traces of the package, including configuration files, use `purge` instead of `remove`.

`apt` will display the amount of disk space removing the package will free up.
Enter *Y* and press **Enter** to confirm removal of the package. You can skip this confirmation step by adding the `-y` flag to the command above.

==== Manage `apt` disk usage

Before running, `sudo apt full-upgrade` shows the amount of data you'll need to download and store on disk to complete an upgrade. To check that you have enough free disk space, run the following command:

[source,console]
----
$ df -h
----

`apt` stores downloaded package (`.deb`) files in `/var/cache/apt/archives`. During installation, `apt` downloads these packages, then copies files from the packages to the correct installation locations. Depending on the software you have installed, package files can take up significant amounts of space. To delete any lingering package files, run the following command:

[source,console]
----
$ sudo apt clean
----

=== Upgrade your operating system to a new major version

WARNING: Before attempting a major version upgrade, make a backup.

To update the operating system to a new major release on your Raspberry Pi, image a second SD card with the new release. Use a USB SD card reader or network storage to copy files and configuration from your current installation to the new SD card. Then, swap the new SD card into the slot on your Raspberry Pi, and boot.

[[rpi-update]]
=== Upgrade your firmware

WARNING: Before attempting a firmware upgrade, make a backup.

WARNING: Pre-release versions of software are not guaranteed to work. Do not use `rpi-update` on any system unless recommended to do so by a Raspberry Pi engineer. It could leave your system unreliable or broken. Do not use `rpi-update` as part of any regular update process.

To update the firmware on your Raspberry Pi to the latest version, use https://github.com/raspberrypi/rpi-update[`rpi-update`].

`rpi-update` downloads the latest pre-release version of the Linux kernel, its matching modules, device tree files, and the latest versions of the VideoCore firmware. It then installs these files into an existing Raspberry Pi OS install.

All the source data used by `rpi-update` comes from the https://github.com/raspberrypi/rpi-firmware[`rpi-firmware` repository]. This repository contains a subset of the data from the https://github.com/raspberrypi/firmware[official firmware repository].

Run `rpi-update` as root to initiate the update. Once the update is complete, reboot your Raspberry Pi for these changes to take effect:

[source,console]
----
$ sudo rpi-update
$ sudo reboot
----

[.whitepaper, title="Updating Raspberry Pi firmware", subtitle="", link=https://pip.raspberrypi.com/documents/RP-003476-WP-Updating-Pi-firmware.pdf]
****
This whitepaper documents how to update the VideoCore firmware in a Raspberry Pi OS image.
****

=== Downgrade firmware to the last stable release

If you update your firmware to the latest release and experience an issue, use the following command to return to the last stable firmware release:

[source,console]
----
$ sudo apt update
$ sudo apt install --reinstall raspi-firmware
----

=== Convert Raspberry Pi OS Lite into Raspberry Pi OS Desktop

You can add the packages that turn the Lite version into the Desktop version by using `apt`.

. Install your preferred desktop windowing system.
* To install Wayland (recommended), run:
+
[source,console]
----
$ sudo apt install rpd-wayland-core
----
* To install X, run:
+
[source,console]
----
$ sudo apt install rpd-x-core
----
. Install the Raspberry Pi theme and Control Centre.
+
[source,console]
----
$ sudo apt install rpd-theme
$ sudo apt install rpd-preferences
----
. Add the applications.
+
[source,console]
----
$ sudo apt install rpd-applications
$ sudo apt install rpd-utilities
$ sudo apt install rpd-developer
$ sudo apt install rpd-graphics
----
. Add the extra features for your chosen windowing system, such as screenshot and remote desktop capabilities.
* For Wayland, run:
+
[source,console]
----
$ sudo apt install rpd-wayland-extras
----
* For X, run:
+
[source,console]
----
$ sudo apt install rpd-x-extras
----
. Restart your Raspberry Pi to enter the desktop environment.
+
[source,console]
----
$ sudo reboot
----

You now have all the packages that comprise Raspberry Pi OS Desktop.

If you want to return to the Lite version of Raspberry Pi OS, you can remove these packages. Alternatively, to have the Lite experience without removing the desktop packages you've installed, use xref:../computers/configuration.adoc#raspi-config[raspi-config] to set your Raspberry Pi to boot to the command line.

You can also install the recommended applications included in Raspberry Pi OS Full by going to your Raspberry Pi main menu and selecting **Preferences > Recommended Software**.