To my /boot/config.txt on Raspberry Pi Model B I added:


Right now nothing happens when i shorten GPIO#3 with ground.

What else needs to be done to make this overlay work: software- and/or hardware-wise?

  • 3
    What Raspbian version are you using? On Rasbpian 2017.08.16 and above, the command you linked should work AFAICS (also, the options you specified are the defaults, so just dtoverlay=gpio-shutdown should behave the same. Apr 30, 2018 at 10:21

5 Answers 5


The "documentation" for gpio-shutdown is

Name:   gpio-shutdown
Info:   Initiates a shutdown when GPIO pin changes. The given GPIO pin
        is configured as an input key that generates KEY_POWER events.
        This event is handled by systemd-logind by initiating a
        shutdown. Systemd versions older than 225 need an udev rule
        enable listening to the input device:

                ACTION!="REMOVE", SUBSYSTEM=="input", KERNEL=="event*", \
                        SUBSYSTEMS=="platform", DRIVERS=="gpio-keys", \
                        ATTRS{keys}=="116", TAG+="power-switch"

        This overlay only handles shutdown. After shutdown, the system
        can be powered up again by driving GPIO3 low. The default
        configuration uses GPIO3 with a pullup, so if you connect a
        button between GPIO3 and GND (pin 5 and 6 on the 40-pin header),
        you get a shutdown and power-up button.
Load:   dtoverlay=gpio-shutdown,<param>=<val>
Params: gpio_pin                GPIO pin to trigger on (default 3)

        active_low              When this is 1 (active low), a falling
                                edge generates a key down event and a
                                rising edge generates a key up event.
                                When this is 0 (active high), this is
                                reversed. The default is 1 (active low).

        gpio_pull               Desired pull-up/down state (off, down, up)
                                Default is "up".

                                Note that the default pin (GPIO3) has an
                                external pullup.

        debounce                Specify the debounce interval in milliseconds
                                (default 100)

I have used gpio-shutdown to implement a shutdown button (although I use GPIO5 - pin 29 as I use the default for I²C).

The "documentation" does not explain what happens in another pin is used - it does state "This overlay only handles shutdown".

Pin 5 USED to perform a restart on older Pi - See Will pulling pin 5 low will make the pi boot up again but this does not seem to work.

Update Pin 5 WILL restart; gpio-poweroff had disabled it.

Name:   gpio-poweroff
Info:   Drives a GPIO high or low on poweroff (including halt). Enabling this
        overlay will prevent the ability to boot by driving GPIO3 low.

Indeed there seems to be little point in modern 40 pin Pi - which have a dedicated Run input which can be used to restart the Pi.

PS If you are using the default ,active_low=1,gpio_pull=up seems unnecessary as there is an external pullup, and active_low is the default.

  • 1
    About the default parameters, the line dtoverlay=gpio-shutdown,gpio_pin=3 is enough?
    – madneon
    Jan 18, 2018 at 10:34
  • 1
    Strictly you do not need ,gpio_pin=3 which is the default (but a poor choice as it is used for I²C).
    – Milliways
    Jan 18, 2018 at 10:56
  • 1
    I chose GPIO3 because it also "wakes" the Raspberry Pi 3B, so one pin could work both ways: to turn on and off.. IF it works ;)
    – madneon
    Jan 18, 2018 at 20:01

Go to this link and search for 'gpio-shutdown', it will give you steps to implement the gpio shutdown: https://www.stderr.nl/Blog/Hardware/RaspberryPi/PowerButton.html


I do not know what version of the firmware you are using, but for any current version on the RPi 3B, or RPi 4B this two-step procedure by @MatthijsKooijman still works. It may also work on other versions, but I've not tested it.

In other words: It seems that you have made an error somewhere, or your configuration has been altered. Follow the detailed procedure below, incl. the verification. If it doesn't work, please post the following information:

  • list all active lines in your /boot/config.txt
  • Pi 4 only: run rpi-eeprom-config & post the results

Step 1: add one line to /boot/config.txt:


Note that gpio_pin 3 is physical pin 5 - the SCL line for the default I2C bus - I2C1. If you're using I2C (if it's enabled), that is OK - you only need to avoid I2C1 in your configuration. For example, I use I2C for my Real Time Clock (RTC), which by default uses I2C1. Consequently, I moved the RTC to I2C0 before verifying this answer.

Step 2: Connect a momentary pushbutton switch between physical pin 5 and GND on the RPi:

Shutdown the RPi, and remove power (pull the plug) before making the wiring connections shown below. Two wires and a momentary PB switch are all that's required.


simulate this circuit – Schematic created using CircuitLab


Re-apply power to the RPi, and verify that it starts and responds normally (as it did before making the changes in Steps 1 & 2). Login to the RPi via SSH.

If you have a USB power meter, note the voltage and current to the RPi while running. On my RPi 4B system: 4.99V ≤ V ≤ 5.02V & 400mA ≤ I ≤ 470mA

Press and release SW1 - the momentary pushbutton:

The RPi should have shutdown "safely". Note the voltage and current to the RPi afterwards. On my RPi 4B system: Vin = 5.06V & Iin = 270mA. Verify that the SSH session you started has closed with a message similar to: Connection to raspberrypi4b.local closed by remote host.

Press and release SW1 again:

The RPi should re-start. Verify this by initiating another SSH session to the RPi and/or by observing the voltage & current input resume normal/running levels.

Beware of conflicts:

The RPi 4 has a "low-power mode" configuration that may be set in the EEPROM bootloader configuration using parameters WAKE_ON_GPIO=0 & POWER_OFF_ON_HALT=1. When this configuration is set, and with the RPi 4 running, a press & release of SW1 will shutdown the system, placing it in "low power mode". However, the RPi 4 can only be re-started by cycling power or toggling the GLOBAL-EN node; i.e. connect GLOBAL_EN to ground & then release. This behavior verified on the following RPi 4B firmware image: Thu 29 Apr 16:11:25 UTC 2021 (1619712685)

Future-Proof this answer:

The configuration parameters for RPi are in flux, and it is a given that they will remain in flux. While this answer was valid when submitted, conditions will change at some point. Please consult /boot/overlays/README on your system to verify the instructions remain essentially unchanged from this baseline version

  • Hi. Do I need to put the button exactly in between GPIO 3 and GND of the Pi? Asking so because when I connect the GND from the button to the common ground on the breadboard (share with other components, and to GND of Pi 4), it does not work. But when I connect directly gpio3-button-GND (of Pi) like your schematic, it works..
    – Lam Le
    Apr 11 at 18:20
  • 1
    @LamLe: There must be something wrong with your wiring - that, or you have separate GNDs; i.e. GND1 & GND2, where GND1 GND2
    – Seamus
    Apr 11 at 21:28
  • Thank you. I've tried another board and it works now with the common ground. Indeed was a wiring issue somewhere. May I ask something else? I use the same dtoverlay in your answer, but to turn off, I have to press the button twice. Pressing the first time will open the Shutdown Options menu (on the screen). And then pressing the next time right after that will shut down. Two times to shut down is the default..?
    – Lam Le
    Apr 12 at 20:45
  • @LamLe: Please post this as a new question... off the top of my head I don't know why this is happening to you. When you post new question, be sure to provide details such as OS version & if you're running from GUI or "command line".
    – Seamus
    Apr 12 at 20:52

It's been a while since the question, and @Seamus gave a good answer, but I had the same issue and nothing in the other answers worked for me.

I was using Pin 3 for shutdown and Pin 2 for gpio default on as a power indicator, both configured as:

dtoverlay=gpio-shutdown, active_low, gpiopin=3

in /boot/config.txt . Pin 3 was not shutting it down and Pin 2 was not lighting the LED.

Above that in the same file is

# Uncomment some or all of these to enable the optional hardware interfaces

(this was the default config for me.)

Commenting out those two lines


fixed it for me. I assume this is because pins 2 and 3 are used for I2C and that was somehow taking priority? (Someone please feel free to fill me in in the comments.)

  • The I2C buses are disabled by default. You must have either added the device tree parameter to /boot/config.txt, or enabled it using raspi-config. Were you using I2C for anything? If so, know that i2C1 is the default channel, but another channel may be usable - depending on your configuration.
    – Seamus
    Oct 18, 2021 at 19:51

Using Raspi 3B+. At first remove all spaces from the string: "dtoverlay=gpio-shutdown, active_low, gpiopin=3" At second you should write a value after "active_low" My variant is dtoverlay=gpio-shutdown,gpio_pin=21,active_low=1,gpio_pull=up When I'm trying to shutdown my RasPi, I have to connect 21st pin to ground twice. The first time makes a "loguot" windows to appear, the second one confirms shutdown. But when I try to powerup I still have to use the default pin - GPIO3. The low level on it wakes up RasPi.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.