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

4 Answers 4


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


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

Your Answer

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

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