Return to Raspberry Pi

The raspi-config tool helps you to configure your Raspberry Pi; several settings can be changed with this tool without having to know the correct Raspberry Pi OS commands to use. It is written as a bash script, run in a terminal window, and uses whiptail (whiptail is a “dialog” replacement using newt instead of ncurses, see “man whiptail”) to create the windows, menus and messages. Some changes require administrator permissions, so the tool must be run in a terminal with:

sudo raspi-config

This can be run from the command line or from a terminal window if using the GUI. Older versions of Raspbian would boot to the command line and the raspi-config tool would run on first boot after Raspberry Pi OS installation. Newer versions boot to the GUI and do not run raspi-config. There is a similar GUI configuration tool that can be run from the menus.

Although it is already installed on Raspberry Pi OS, and there is an update Raspberry Pi OS option within the menus, it is installed or updated from package raspi-config.

It has the following entries (this is the layout from raspi-config version 20160108, January 2016). It may be different on other Raspberry Pi OS images:

Raspberry Pi Software Configuration Tool (raspi-config)

• 1 Expand Filesystem Ensures that all of the SD card storage is av…
• 2 Change User Raspberry Pi OS Password Change password for the default user (pi)
• 3 Boot Options Choose whether to boot into a desktop environ…
• 4 Wait for Network at Boot Choose whether to wait for network connection…
• 5 Internationalisation Options Set up language and regional settings to matc…
• 6 Enable Camera Enable this Pi to work with the Raspberry Pi …
• 7 Add to Rastrack Add this Pi to the online Raspberry Pi Map (R…
• 8 Overclock Configure overclocking for your Pi
• 9 Advanced Options Configure advanced settings
• 0 About raspi-config Information about this configuration tool

                                      
  
  
  
  
  The Advanced Options option is another menu:
       Raspberry Pi Software Configuration Tool (raspi-config)
  
  A1 Overscan        You may need to configure overscan if black bars are ...
  A2 Hostname        Set the visible name for this Pi on a network
  A3 Memory Split    Change the amount of memory made available to the GPU
  A4 SSH             Enable/Disable remote command line access to your Pi ...
  A5 Device Tree     Enable/Disable the use of Device Tree
  A6 SPI             Enable/Disable automatic loading of SPI kernel module...
  A7 I2C             Enable/Disable automatic loading of I2C kernel module
  A8 Serial          Enable/Disable shell and kernel messages on the seria...
  A9 Audio           Force audio out through HDMI or 3.5mm jack
  A0 Update          Update this tool to the latest version
  
                                      

  Where the description is too long to fit on a single line it is shown truncated, but above it is shown with “…” (the dots are not shown on your Pi).

  Moving Around the Menu

  Cursor up/down keys move the highlight up and down menus, stopping at the top or bottom.

  The Tab key switches from the selected menu entry and the “buttons” at the bottom (inside angle brackets), and back again.

  With a menu entry or a “button” highlighted, press Enter to start that option or button.

  Pressing ESC quits from the menus, without confirmation. Whiptail has a 'hotkey' capability which does not apply in raspi-config.

  Some of the menu entries take a while to read configuration information before they change what is displayed. Be patient.

  What raspi-config does

  Some menu entries modify the file /boot/config.txt. This file, out of the box, contains a number of commented out configuration entries; raspi-config adds entries at the end of this file. You can see what raspi-config has done to the file by viewing it on the Pi using Leafpad. More information on editing config.txt here R-Pi_ConfigurationFile

  Other entries modify Linux configuration files. Some take effect immediately, others at the next boot.

  Menu Options

  Here is a description of each menu entry.

  info - Information About This Tool

  It helpfully advises that it is for initial configuration, and can be run at any time. You may have difficulties if you have heavily customized your installation as the changes it makes might not be correct if what it attempts to change is not what it expects.

  expand_rootfs - Expand root partition to fill SD card

  The usual distribution images are 2 GB. When you copy the image to a larger SD card you have a portion of that card unused. This option expands the initial image to expand to fill the rest of the SD card, giving you more space. You need to reboot the Raspberry Pi to make this available. THERE IS NO CONFIRMATION - SELECTING THE OPTION EXPANDS THE PARTITION.

  overscan - Change overscan

  Old photographs had a border round the outside to allow for handling and mounting. Old TV sets had a significant variation in the size of the picture it produced; some had cabinets that overlapped the screen. Like the photographs, the TV pictures were given a black border so that none of the picture was lost. This is called overscan. Modern TVs and monitors don't need, and the signal doesn't have, the border. If the initial text shown on the screen disappears off the edge you need to enable overscan to add back the border.

  Any changes will take effect after a reboot. You can have greater control over the settings by editing boot/config.txt.

  On some displays, particularly monitors, just disabling Overscan will make the picture fill the whole screen and correct the resolution. For other displays it may be necessary to leave overscan enabled and adjust the Overscan values, more information here Big_black_borders_around_small_image_on_HD_monitors.

  configure-keyboard - Set keyboard layout

  This option selects the keyboard being used, so that the characters produced are the same as those typed (important examples are # and /). It is slow to display, while it reads all the keyboard types. Changes usually take effect immediately, but may require a reboot.

  Brands of keyboards are chosen first followed by other choices to set up the nationality of the keyboard. The default is a Generic 105-key (Intl) PC. If you cannot find your keyboard on the list then use one of the generic keyboards. Check | this page for most keyboard layouts. The next screen gives the keyboard layout. If you are not using the first choice of English UK select Other and you will be faced with a long list of other national keyboards.

  You then select specific options:

  • No AltGr key
  • Compose key — Many people choose not to set up a Compose key, but it can be useful for typing symbols or accented characters on a regular keyboard. If you wish to define a Compose key, instructions on how to do so are here: Compose key.
  • Shutdown XServer (use [Ctrl][Alt][Backspace] all pressed at the same time)

  change_pass - Change password for ‘pi’ user

  The default user for the Raspian install is “pi” and its password is “raspberry”. If you change the password, other people will need to know the new password, including you, to logon to the Raspberry Pi. Each user/password combination can be different on each SD card.

  change_locale - Set locale

  This option selects the characters and other symbols being displayed on the screen, and is important if you want to use the non-english ones. It is slow to display, while it reads all the locale information. Changes usually take effect immediately, but may require a reboot.

  You usually select only the one(s) you want (press space); this will generate the configuration data for all those you select. The default setting is en_GB UTF-8 UTF-8

  change_timezone - Set timezone

  This is where you setup your system clock; if it’s wrong it just means the date and time assigned to files you create (automatically when you make them) will be wrong. It is slow to display as there are lots of selections. First you select the continent, then select a City from that continent. You may have to select the one nearest to you.

  The Raspberry Pi does not have an onboard clock (you can add one), so the “clock” stops when you power it off. If you are connected to the internet the Raspberry Pi can be set up to get the time from an online time signal.

  memory_split - Change memory split

  The Raspberry Pi has two processors, one for calculation tasks (the CPU) and one for graphical tasks (the GPU). The CPU is described as the ARM; the GPU as the VideoCore. This version takes account of the 256 MB or 512 MB boards, and allows a dynamic reallocation of memory, whereas older versions of raspi-config only split the 256 MB and could not set the dynamic option. The best setting will depend on what type of applications you are running on your Raspberry Pi.

  ssh - Enable or disable ssh server

  Enabling ssh will allow you to connect to your Raspberry Pi from another device on your network and use a terminal window remotely. You do not need a monitor or keyboard connected to your Raspberry Pi if you do this.

  Unless you want to use the Raspberry Pi remotely you can disable this, as it stops the ssh service which takes a small amount of processing resources. If you want to set this up, see the ssh page.

  boot_behaviour - Start desktop on boot?

  The official images are supplied with the Raspberry Pi booting into a command line, presumably because problems with connecting the display are fewer and simpler. If you think you are ok with the GUI interface you can boot to this. You can change this at any time.

  • Desktop (GUI interface) - gives a picture based screen, similar to a Windows, Mac or smartphone, that requires a mouse to select actions (usually). This option also skips the login by using the pi user. Pressing the red Exit button on the right hand side of the screen will give the options to logout, shutdown or reboot. Using logout will give a GUI login screen. Using Ctrl-Alt-Backspace also gives a GUI login screen. To use a command line open the Terminal window. To get back to the command line, logout and press Ctrl-Alt-F1. To permanently get back the command line, run raspi-config and reset the boot behaviour and restart.

  • Command line - gives a text based screen that requires the user to type commands on the keyboard only. Usually the mouse is not required, but some command line programs can use mouse control. You can switch to the GUI screen by typing “startx” and pressing 'Enter'. This time the red Exit button on the right hand side of the screen will only give the option to logout. This returns you to the command line. To stop or reboot the Raspberry Pi type “sudo halt” or “sudo reboot” and press 'Enter'.

  update - Try to upgrade raspi-config

  The raspi-config utility has changed quite a bit since it started, and is likely to continue to change. Use this option to check if your version of raspi-config is the latest, and if not download the latest version; you will need to be connected to the internet to update it. Once updating is complete, raspi-config will close. You should restart raspi-config with “sudo raspi-config” to make sure that you have completed all the options.

  <Finish>

  Use this 'button' when you have completed your changes. You will be asked whether you want to reboot or not. When used for the first time its best to reboot. This should restart your Pi. There will be a delay if you have chosen to resize your SD card.

  First-boot activity

  When a new image that contains the raspi-config utility is booted the first time, the session starts with the raspi-config screen. Use the help above when using the utility on first boot. This behaviour is driven by the raspi-config.sh script in the /etc/profile.d directory.

  #!/bin/sh
  # Part of raspi-config http://github.com/asb/raspi-config
  #
  # See LICENSE file for copyright and license details
  
  # Should be installed to /etc/profile.d/raspi-config.sh to force raspi-config
  # to run at initial login
  
  # You may also want to set automatic login in /etc/inittab on tty1 by adding a
  # line such as:
  # 1:2345:respawn:/bin/login -f root tty1 </dev/tty1 >/dev/tty1 2>&1 # RPICFG_TO_DISABLE
  
  if [ $(id -u) -ne 0 ]; then
    printf "\nNOTICE: the software on this Raspberry Pi has not been fully configured. Please run 'sudo raspi-config'\n\n"
  else
    raspi-config
    exec login -f pi
  fi

  This runs the raspi-config script (found as /usr/bin/raspi-config). When that has completed, the script above shows the login prompt for the pi user.

  When the raspi-config script runs, and the user selects the Finish option, the script above is deleted so that it will not run again. When the Raspberry Pi is first booted it uses the /etc/inittab script, which does an automatic login as root. The Finish option of the raspi-config script modifies part of the inittab script, from the login as root:

  ...
  # 1:2345:respawn:/sbin/getty --noclear 38400 tty1 # RPICFG_TO_ENABLE
  1:2345:respawn:/bin/login -f root tty1 </dev/tty1 >/dev/tty1 2>&1 # RPICFG_TO_DISABLE
  2:23:respawn:/sbin/getty 38400 tty2
  3:23:respawn:/sbin/getty 38400 tty3
  ...

  to the standard login action:

  ...
  1:2345:respawn:/sbin/getty --noclear 38400 tty1
  2:23:respawn:/sbin/getty 38400 tty2
  3:23:respawn:/sbin/getty 38400 tty3
  ...

  History

  This utility script was first released with the Debian Wheezy image of 18 June 2012. It is expected to continue changing so the number of menu items and the ease of use of those items will increase with time. If anyone feels willing and able to improve raspi-config then please contact Alex Bradbury s://github.com/asb/raspi-config.

  Is this useful?

  This may be just a bit of background information, but it could be useful if you wish to distribute your own SD cards to friends, based on your own configuration. You may have added or removed packages, changed configurations, or any number of things that you and your friends think are useful.

  You can create a backup image of your SD card, but that image will not execute the raspi-config script on first boot; your friends may need to run it because they have different hardware. To make that script run automatically, copy the top script to /etc/profile.d/raspi-config.sh and change the /etc/inittab script back to the original lines.

  RPi Linux