Set up a Raspberry Pi on/off button

Before you start

You’ll need a Raspberry Pi with an accessible 40-pin GPIO header, Raspberry Pi OS, and a normally open momentary push button with two connection wires. For the Windows method, you’ll also need an SD card reader.

Check your board.

This guide describes the GPIO button method used on boards such as Pi 3 and Pi 4. Starting the Pi again with GPIO 3 depends on the board and its power settings. Pi 5 and later have dedicated power-button behavior; check your model’s instructions before applying this setup.

The button requests a software shutdown; it does not disconnect the power supply. GPIO 3 also serves as I²C clock, so check for conflicts with attached accessories.

01 Connect the button

Shut down the Pi and disconnect its power before changing the wiring. Connect one button lead to physical pin 5 (GPIO 3) and the other to physical pin 6 (GND). Seat both connectors fully.

PHYSICAL PIN 5GPIO 3

↔ Button ↔

PHYSICAL PIN 6Ground

Physical pin numbers and GPIO numbers are different. Use the two pins shown above; do not connect the button to a 5V or 3.3V power pin.

02 Configure your Pi

Choose one of these methods. Both add the same overlay line to config.txt. Make a backup of the file before editing it.

METHOD A

On the Raspberry Pi

Reconnect power and boot your Pi. Open Terminal.
On current Raspberry Pi OS, open the configuration file:
```
sudo nano /boot/firmware/config.txt
```
On older installations, the location is /boot/config.txt. Edit the existing boot configuration file for your OS.
At the end of the file, add an [all] section if needed so the setting applies to your board, then add this line once:
```
[all]
dtoverlay=gpio-shutdown,gpio_pin=3,active_low=1,gpio_pull=up,debounce=200
```
Save in nano: press Ctrl + X, then Y, then Enter.
Restart to apply the change:
```
sudo reboot
```

METHOD B

From a Windows computer

Shut down the Pi, disconnect power, and remove its microSD card.
Insert the card into your Windows computer. Open the readable boot partition in File Explorer.
Open the existing config.txt file with Notepad, rather than a word processor. At the end, add an [all] section if needed and the same overlay line:
```
[all]
dtoverlay=gpio-shutdown,gpio_pin=3,active_low=1,gpio_pull=up,debounce=200
```
Save as plain text without changing the filename to config.txt.txt. Safely eject the card.
Return the card to the Pi, reconnect power, and boot normally.

Windows only needs access to the boot configuration file for this method. It will not normally read the Pi’s Linux filesystem. If Windows offers to format an unreadable partition, cancel.

03 Test the button

Save your work, then press and release the button. The Pi should begin an orderly shutdown.
Wait for shutdown to finish before disconnecting power or removing the SD card.
On a board configured to wake through GPIO 3, leave power connected and press the button again to start the Pi.

If the button shuts down the Pi but does not wake it, check your model’s bootloader and power settings. Moving to a different GPIO pin does not add wake support.

Other pins & settings

For a shutdown-only button, you can use a different available GPIO and a ground pin. Match gpio_pin to the BCM GPIO number. For example, physical pin 11 is GPIO 17, with ground at physical pin 9:

dtoverlay=gpio-shutdown,gpio_pin=17,active_low=1,gpio_pull=up,debounce=200

debounce=200 filters switch contact bounce for 200 milliseconds. Increasing it is not a reliable way to require a long press. A hold-to-shutdown feature needs a separate implementation.

If it doesn’t work

No response: confirm the physical pins, fully seated wires, and momentary button type. Check that you edited the active config.txt and rebooted.
Conflicting behavior: check whether another overlay, HAT, or I²C device uses GPIO 3.
Shutdown works, startup doesn’t: check your board’s wake support and power configuration.

Need a hand with your setup?

Tell us your Pi model, operating system, and which setup method you used.

Contact Vilros Support ↗