Lesson 01: Setup Your Pi Board

Raspberry Pi Desktop users can access a graphical version of this application at Preferences > Raspberry Pi Configuration. However, some advanced configurations are only available in the raspi-config.

raspi-config helps you configure your Raspberry Pi. Available options may differ between Raspberry Pi models. To open the configuration tool, run the following command:

sudo raspi-config

raspi-config automates edits to /boot/firmware/config.txt and various Linux configuration files. Some options require a reboot to take effect. If you change any of these, raspi-config asks you to reboot when you exit.

Expand filesystem

Expands your OS partition to fill the whole storage device, giving you more space to use for files. Click Advanced Options > Expand filesystem, then reboot your Raspberry Pi to complete this action. Usually, Raspberry Pi OS runs this action on the first boot. This option can be useful if you clone your OS to a separate storage device with more capacity than the original.

Enable SSH, VNC, SPI, I2C, Serial Port and 1-Wire Interfaces

Click the 'Interface Options' to enable and disable various physical and virtual interfaces.

Configure Localisation options

Click 'Localisation Options" to configure location, timezone, keyboard, and WLAN country-related options.

Screen Blanking

You can configure your Raspberry Pi to blank the screen after a period of inactivity. By default, Raspberry Pi OS blanks the screen after ten minutes of inactivity when screen blanking is enabled.

• Raspberry Pi Configuration:
  • Click the Raspberry Pi button in the menu bar. Navigate to Preferences > Raspberry Pi Configuration.
  • Select the Display tab. Toggle the Screen Blanking radio button into the on position. Press OK to confirm your selection
• CLI:
  • You can enable and disable screen blanking with the raspi-config CLI tool. Run the following command to open the tool.
    

    sudo raspi-config

  • Use the arrow keys to navigate and the Enter key to select. Select Display Options > Screen Blanking. Choose yes with the arrow keys to enable screen blanking or no to disable screen blanking.

The raspi-config tool also supports non-interactive options and flags that change options entirely on the command line with no visual component. Available options may differ between Raspberry Pi models.

sudo raspi-config nonint <command> <arguments> [optional-argument]

Note: The meaning of 0 and 1 varies between options. Always check the documentation before passing a value to an option.

System options

Wireless LAN

Configure Wi-Fi SSID and passphrase.

sudo raspi-config nonint do_wifi_ssid_passphrase <ssid> <passphrase> [hidden] [plain]

Pass a wireless network name (SSID) and passphrase, if required. The following flags are optional:

The <hidden> option indicates the visibility of the SSID. If the network broadcasts an open SSID, pass 0 or omit the option. If your SSID is hidden, pass 1. Defaults to 0.

The <plain> option indicates whether or not you intend to pass the passphrase as plaintext. If your passphrase includes a space or a special character like !, you must pass 0 and use quotes around your passphrase. Otherwise, you can pass 1 or omit the option. Defaults to 1. To pass this option, you must specify a value for <hidden>.

For example, run the following commands to connect to a:

• non-hidden network named myssid with the passphrase mypassphrase:

sudo raspi-config nonint do_wifi_ssid_passphrase myssid mypassphrase

• hidden network named myssid with the passphrase mypassphrase:

sudo raspi-config nonint do_wifi_ssid_passphrase myssid mypassphrase 1

• non-hidden network named myssid with the passphrase my passphrase:

sudo raspi-config nonint do_wifi_ssid_passphrase myssid "my passphrase" 0 0

Audio

Specify the audio output destination.

sudo raspi-config nonint do_audio <N>

On Raspberry Pi 4B, you can use the following options:

• 0: bcm2835 headphone jack
• 1: vc4-HDMI-0
• 2: vc4-HDMI-1

For a full list of possible <N> values, see the numbers used in the interactive raspi-config version of this option.

Password

Change your password. (For more information, see Change a user’s password.)

sudo raspi-config nonint do_change_pass

Note: This function uses a full-screen interactive interface, even when run from a CLI option.

Hostname

Set the visible mDNS name for this Raspberry Pi on a network.

sudo raspi-config nonint do_hostname <hostname>

Boot/auto login

Select whether to boot to the console or desktop and whether or not your Raspberry Pi automatically logs into your current user account when powered on.

sudo raspi-config nonint do_boot_behaviour <B1/B2/B3/B4>

• B1: boot to console, requiring login
• B2: boot to console, logging in automatically
• B3: boot to desktop, requiring login
• B4: boot to desktop, logging in automatically

Network at boot

Wait for a network connection before letting the boot proceed.

sudo raspi-config nonint do_boot_wait <0/1>

• 0: boot without waiting for network connection
• 1: boot after waiting for network connection

Splash screen

Enable or disable the splash screen displayed at boot time.

sudo raspi-config nonint do_boot_splash <0/1>

• 0: enable splash screen
• 1: disable splash screen

Power LED

If your Raspberry Pi model allows, change the behavior of the power LED.

sudo raspi-config nonint do_leds <0/1>

• 0: flash for disk activity
• 1: keep the power LED lit at all times

Browser

Change the default web browser. Choosing a web browser that isn’t currently installed won’t work.

sudo raspi-config nonint do_browser <chromium-browser/firefox>

Display Options

Underscan

Note: Not available when running Wayland.

If the initial text on the screen disappears off the edge, enable overscan to adjust the border. Disabling overscan on some displays, particularly monitors, will make the picture fill the whole screen and remove the black border.

sudo raspi-config nonint do_overscan_kms <device> <enabled>

Device:

• 1: HDMI-1
• 2: HDMI-2

Enabled:

• 0: enable overscan
• 1: disable overscan

Screen blanking

Enable or disable screen blanking.

sudo raspi-config nonint do_blanking <0/1>

• 0: enable screen blanking
• 1: disable screen blanking

you can add or edit the following lines to ~/.config/wayfire.ini:

[idle]
dpms_timeout=600

The dpms_timeout variable controls the number of seconds of inactivity required before Raspberry Pi OS blanks your screen. For example, a value of 600 blanks the screen after 600 seconds or ten minutes. Set the value to 0 to never blank the screen.

VNC Resolution

Define the video resolution to use for VNC in headless setups.

sudo raspi-config nonint do_vnc_resolution <width>x<height>

Composite

Enable or disable composite video output.

On Raspberry Pi 4:

sudo raspi-config nonint do_pi4video <V1/V2/V3>

• V1: enable 4Kp60 HDMI output
• V2: enable composite video output
• V3: disable 4Kp60 and composite output

On other models:

sudo raspi-config nonint do_composite <0/1>

• 0: enable composite video
• 1: disable composite video

Interface Options

SSH

Enable or disable remote terminal access to your Raspberry Pi using SSH.

SSH allows you to remotely access the command line of the Raspberry Pi from another computer. For more information about SSH.

sudo raspi-config nonint do_ssh <0/1>

• 0: enable SSH
• 1: disable SSH

VNC

Enable or disable a Virtual Network Computing (VNC) server. For more information about VNC, see the VNC documentation.

sudo raspi-config nonint do_vnc <0/1>

• 0: enable VNC
• 1: disable VNC

SPI

Enable or disable SPI interfaces and automatic loading of the SPI kernel module.

sudo raspi-config nonint do_spi <0/1>

• 0: enable SPI
• 1: disable SPI

I2C

Enable or disable I2C interfaces and automatic loading of the I2C kernel module.

sudo raspi-config nonint do_i2c <0/1>

• 0: enable I2C
• 1: disable I2C

Serial Port

Enable or disable the serial connection hardware.

sudo raspi-config nonint do_serial_hw <0/1/2>

• 0: enable serial port
• 1: disable serial port

Serial console

Enable or disable shell and kernel messages on the serial connection.

sudo raspi-config nonint do_serial_cons <0/1/2>

• 0: enable console over serial port
• 1: disable console over serial port

1-wire

Enable or disable the Dallas 1-wire interface. This is usually used for DS18B20 temperature sensors.

sudo raspi-config nonint do_onewire <0/1>

• 0: enable 1-wire
• 1: disable 1-wire

Remote GPIO

Enable or disable remote access to the GPIO pins.

sudo raspi-config nonint do_rgpio <0/1>

• 0: enable remote GPIO
• 1: disable remote GPIO

Performance options

Overclock

If your Raspberry Pi model allows, overclock the CPU. Overclocking potential varies between individual Raspberry Pi devices, even within the same model. Overclocking too high may result in instability.

Warning: Overclocking may reduce the lifetime of your Raspberry Pi. If overclocking at a certain level causes system instability, try a more modest overclock. Hold down the Shift key during boot to temporarily disable overclocking.

sudo raspi-config nonint do_overclock <setting>

This command accepts the following <setting> values:

• None: no overclock (default)
• Modest: overclock to 50% of the maximum
• Medium: overclock to 75% of the maximum
• High: overclock to 100% of the maximum
• Turbo: overclock to 125% of the maximum

GPU memory

Change the amount of memory made available to the GPU.

sudo raspi-config nonint do_memory_split <megabytes>

Overlay file system

Enable or disable a read-only filesystem.

sudo raspi-config nonint do_overlayfs <0/1>

• 0: enable overlay filesystem
• 1: disable overlay filesystem

Fan

Customize the behavior of the GPIO-connected Raspberry Pi 4 Case Fan. Does not affect the fans in the Raspberry Pi 5 Case for Raspberry Pi 5 or Raspberry Pi 5 Active Cooler, which connect using a special four-pin fan header.

sudo raspi-config nonint do_fan <0/1> [gpio] [onTemp]

• 0: enable fan
• 1: disable fan

gpio defaults to 14.

onTemp defaults to 80 degrees Celsius.

Localisation options

Locale

Select a locale, for example en_GB.UTF-8 UTF-8.

sudo raspi-config nonint do_change_locale <locale>

For a full list of possible <locale> values, see the abbreviations used in the interactive raspi-config version of this option.

Time zone

Set your local time zone, starting with the region then selecting a city, e.g. "America/Los Angeles".

sudo raspi-config nonint do_change_timezone <timezone>

For a full list of possible <timezone> values, see the abbreviations used in the interactive raspi-config version of this option.

Keyboard

Set your keyboard layout. Changes usually take effect immediately but may require a reboot.

sudo raspi-config nonint do_configure_keyboard <keymap>

For a full list of possible <keymap> values, see the abbreviations used in the interactive raspi-config version of this option.

WLAN country

Set the country code for your wireless network.

sudo raspi-config nonint do_wifi_country <country>

For a full list of possible <country> values, see the abbreviations used in the interactive raspi-config version of this option.

Advanced options

Expand filesystem

Expand your OS partition to fill the whole storage device, giving you more space to use for files. Reboot the Raspberry Pi to complete this action. Usually, Raspberry Pi OS runs this action on the first boot. This option can be useful if you clone your OS to a separate storage device with more capacity than the original.

Warning: There is no confirmation step. Selecting the option begins the partition expansion immediately.

sudo raspi-config nonint do_expand_rootfs

Network interface names

Enable or disable predictable network interface names.

sudo raspi-config nonint do_net_names <0/1>

• 0: enable predictable network interface names
• 1: disable predictable network interface names

Network proxy settings

Configure the network’s proxy settings.

sudo raspi-config nonint do_proxy <SCHEMES> <ADDRESS>

Boot order

On the Raspberry Pi 4 and later, specify whether to boot from USB or network if the SD card isn’t inserted. See the bootloader configuration section for more information.

sudo raspi-config nonint do_boot_order <B1/B2/B3>

Depending on your device, you can choose from the following options:

• B1: SD card boot - Boots from SD card if available; otherwise, from NVMe; if neither, from USB.
• B2: NVMe/USB boot - Boots from NVMe if available; otherwise, from USB; if neither, from SD card.
• B3: Network boot - Boots from SD card if inserted; otherwise, from the network.

Bootloader version

On the Raspberry Pi 4 and later, switch to the latest boot ROM software. Alternatively, you can revert to the factory default if the latest version causes problems.

sudo raspi-config nonint do_boot_rom <E1/E2>

• E1: use the latest boot ROM
• E2: use the factory default

Wayland

Switch between the X11 and Wayland backends. Raspberry Pi 4 and later use Wayland by default; other models of Raspberry Pi use X11 by default.

sudo raspi-config nonint do_wayland <W1/W2>

• W1: use the X11 backend
• W2: use the Wayland backend

Note: To use Wayland on Raspberry Pi models before Raspberry Pi 4, add wayland=on to /boot/firmware/cmdline.txt.

Audio config

Use this option to switch between the PulseAudio and PipeWire audio backends. Before Raspberry Pi OS Bookworm, Raspberry Pi OS used PulseAudio.

sudo raspi-config nonint do_audioconf <1/2>

• 1: use the PulseAudio backend
• 2: use the PipeWire backend

Update

Update this tool to the latest version.

sudo raspi-config nonint do_update

• First, identify the UUID for your SSD:

  lsblk -f

  Write the UUID value under nvme0n1.
• Then, add a new entry to the fstab file:

  sudo nano /etc/fstab

• Insert the following line, replacing the UUID with the value found from lsblk -f:

  UUID=************-****-****-****-******** /ssd/ ext4 defaults 0 2

• Finally, change the ownership of the /ssd directory.

  
  sudo chown ${USER}:${USER} /ssd
  

To ensure the SSD is automatically mounted on boot, you can edit the /etc/fstab file:

• Open the file with a text editor:

  sudo nano /etc/fstab

• Add a line for your NVMe SSD. For example:

  /dev/nvme0n1 /ssd ext4 defaults 0 2

  Save and exit.
• Finally, change the ownership of the /ssd directory.

  
  sudo chown ${USER}:${USER} /ssd

This method works if you have an SD card and have booted the device successfully.

1. Boot from SD Card: Ensure your Raspberry Pi 5 is booted from an SD card with Raspberry Pi OS.
2. Open SD Card Copier: Go to Applications -> Accessories -> SD Card Copier.
   
3. Copy OS to SSD: Use the SD Card Copier to clone your OS from the SD card to the NVMe SSD.
4. Shut Down: After copying, shut down the Raspberry Pi, remove the SD card, and restart the device.

1. Prepare Tools: Install Raspberry Pi Imager on a Mac or Windows computer and have a USB to NVMe adapter ready.
2. Flash OS: Use Raspberry Pi Imager to flash Raspberry Pi OS (Bookworm) onto the NVMe SSD.
3. Enable PCIe: If flashing a fresh OS, enable PCIe as described earlier.
4. Boot from SSD: Insert the NVMe SSD into your Raspberry Pi 5 and boot.

Auto TRIM automatically trims the SSD whenever files are deleted. This is done by enabling the discard option in the file system's mount options.

• Edit the Fstab File:
  You may need to ensure the discard option is in the /etc/fstab file for your SSD. Open the file with a text editor:

  
  sudo nano /etc/fstab

• Modify the SSD Mount Options:
  Find the line that mounts your SSD and add discard to the mount options. It might look something like this:

  UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx    /ssd/    ext4    defaults,discard  0   2
  

  or

  /dev/nvme0n1  /ssd    ext4    defaults,discard  0   2
  

  This tells the system to use TRIM on the SSD automatically.
• Save the file, then Reboot the System:
  Reboot your Raspberry Pi to apply the changes:

  
  sudo reboot
  

• Verify TRIM is Working
  After rebooting, you can verify that TRIM is working by running:

  
  sudo fstrim -v /ssd
  

  This command should report the amount of data trimmed, confirming that TRIM is active.

Scheduled TRIM is performed periodically, such as once a week, using a cron job. This method is useful if you want to avoid the potential performance impact of auto TRIM.

• Create a cron job:
  You can set up a cron job to run fstrim periodically, such as once weekly.

  
  sudo crontab -e
  

• Add the following line to schedule TRIM weekly:

  @weekly /sbin/fstrim -v /ssd
  

• Save the file, then Reboot the System:
  Reboot your Raspberry Pi to apply the changes:

  
  sudo reboot
  

• Verify TRIM is working
  After rebooting, you can verify that TRIM is working by running:

  
  sudo fstrim -v /ssd
  

  This command should report the amount of data trimmed, confirming that TRIM is active.

Install Multiple Python Versions Using apt

This method is suitable for installing Python versions available in the Pi OS repositories.

1. Update and Upgrade the System:
   Start by updating the package lists and upgrading existing packages:

   
   sudo apt update
   sudo apt upgrade -y
   

2. Install Python Versions:
   Check the available Python versions in the Linux repositories:

   
   apt-cache search python3
   

   Install the desired Python versions, such as Python 3.8 and Python 3.10:

   
   sudo apt install python3.8 python3.10 -y
   

3. Verify Installed Python Versions:
   You can have multiple Python versions installed simultaneously. To see the installed Python binaries, run:

   
   ls /usr/bin/python*
   /usr/bin/python /usr/bin/python3.8 /usr/bin/python3-config /usr/bin/python-dotenv
   /usr/bin/python3 /usr/bin/python3.11-config /usr/bin/python3-unidiff
   

4. Check Python Version Details:
   To get precise version information, execute:

   
   python3 -V
   Python 3.11.2
   

5. Manage Python Versions with update-alternatives:
   To switch between Python versions, use the update-alternatives command. First, list all Python alternatives:

   
   sudo update-alternatives --list python
   /usr/bin/python3.8
   /usr/bin/python3.10
       

   If no alternatives are configured, you may see an error message.
6. Configure Python Alternatives:
   Update the alternatives table to include the installed Python versions:

   
   sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.8 1
   update-alternatives: using /usr/bin/python3.8 to provide /usr/bin/python (python) in auto mode
   sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 2
   update-alternatives: using /usr/bin/python3.10 to provide /usr/bin/python (python) in manual mode
   

   • The --install option takes multiple arguments:
     • /usr/bin/python3: Path to the symbolic link.
     • python3: Name of the alternative group.
     • /usr/bin/python3.X: Path to the Python binary.
     • Priority number: Determines the default selection if no manual choice is made. Higher numbers take precedence.
   • In this example:
     • /usr/bin/python3.10 is assigned priority 2.
     • /usr/bin/python3.8 is assigned priority 1.
7. Verify Updated Alternatives:
   List the Python alternatives again:

   
   sudo update-alternatives --list python3
   /usr/bin/python3.8
   /usr/bin/python3.10
   

8. Switch Between Python Versions:
   You can switch between the available Python versions using the --config option:

   
   sudo update-alternatives --config python3
   

   Follow the prompts to select the desired version by entering the corresponding selection number.

Use pyenv for Version Management

pyenv is a popular tool to install and manage multiple Python versions.

1. Install Dependencies:

   
   sudo apt update
   sudo apt install -y build-essential curl libssl-dev zlib1g-dev libbz2-dev \
       libreadline-dev libsqlite3-dev wget llvm libncurses5-dev libncursesw5-dev \
       xz-utils tk-dev libffi-dev liblzma-dev python3-openssl git
   

2. Install pyenv:
   Run the following commands to install pyenv:

   
   curl https://pyenv.run | bash
   

   Add the following lines to your shell configuration file (~/.bashrc or ~/.zshrc):

   
   export PYENV_ROOT="$HOME/.pyenv"
   export PATH="$PYENV_ROOT/bin:$PATH"
   eval "$(pyenv init --path)"
   eval "$(pyenv init -)"
   eval "$(pyenv virtualenv-init -)"
   

   Reload the shell:

   
   exec $SHELL
   

3. Install Python Versions:
   Use pyenv to install the desired Python versions:

   
   pyenv install 3.8.12
   pyenv install 3.10.7
   

4. Set Global or Local Python Version:
   Set a global version:

   
   pyenv global 3.10.7
   

   Set a local version for a specific project directory:

   
   pyenv local 3.8.12

5. Check the current version:

   
   python --version

Build Python Versions from Source

This method is more flexible but requires manual management.

1. Install Build Dependencies:
   sudo apt update

   
   sudo apt update
   sudo apt install -y build-essential libssl-dev zlib1g-dev libncurses5-dev \
       libncursesw5-dev libreadline-dev libsqlite3-dev libgdbm-dev libdb5.3-dev \
       libbz2-dev libexpat1-dev liblzma-dev tk-dev libffi-dev git
   

2. Download Python Source Code:
   Visit the Python downloads page and copy the link to the desired version.
   Download the source code (e.g., Python 3.10.14 and 3.13.0):

   
   wget https://www.python.org/ftp/python/3.10.14/Python-3.10.14.tgz
   wget https://www.python.org/ftp/python/3.13.0/Python-3.13.0.tgz
   

   Extract the tarball:

   
   tar -xvf Python-3.10.14.tgz
   cd Python-3.10.14
   

3. Build and Install Python:
   Run the following commands:

   
   ./configure --enable-optimizations
   sudo make altinstall
   

   • Use make altinstall instead of make install to avoid overwriting the default Python binary. Repeat the process for other Python versions.
4. Switch Between Python Versions:
   Specify the full path to the version you want to use:

   
   /usr/local/bin/python3.10 --version
   /usr/local/bin/python3.13 --version
   

   Alternatively, create symbolic links:

   
   sudo ln -sf /usr/local/bin/python3.10 /usr/bin/python3.10
   sudo ln -sf /usr/local/bin/python3.13 /usr/bin/python3.13
   

5. Verify Python Versions:
   After installation, check the available versions:

   
   python3 --version
   python3.18 --version
   python3.13 --version
   

By following one of these methods, you can install and manage multiple versions of Python on the system efficiently!

Per-Project Environments

This approach creates a dedicated virtual environment for each Python project, typically located in the project's root folder. This setup ensures that dependencies for one project do not affect others.

1. Create a Virtual Environment
   Navigate to the root folder of your project and run the following command to create a virtual environment folder (commonly named env):

   
   python -m venv env
   

2. Activate the Virtual Environment
   Before working on your project, activate the environment by running:

   
   source env/bin/activate
   

   Once activated, your terminal prompt will indicate the virtual environment is in use.
3. Deactivate the Virtual Environment
   When you finish working, deactivate the virtual environment by running:

   
   deactivate
   

Per-User Environments

For users managing multiple projects with shared dependencies, a single virtual environment for your user account can be more convenient.

1. Create a Global Virtual Environment
   Place the virtual environment in your home directory, using a hidden folder to keep your workspace organized. Run:

   
   python -m venv ~/.env
   

2. Activate the Virtual Environment
   Activate the virtual environment from any directory using:

   
   source ~/.env/bin/activate

   Your terminal prompt will reflect the activation of the environment.
3. Deactivate the Virtual Environment
   When you no longer need the environment, deactivate it by running:

   
   deactivate