The statement import RPi.GPIO as GPIO loads the foundational Python C-extension library that maps high-level software commands to the physical 3.3V logic states of a Raspberry Pi’s 40-pin header. When you execute a command like GPIO.output(pin, GPIO.HIGH), you are not just changing a variable in memory; you are altering the internal hardware multiplexer of the Broadcom SoC, switching a physical silicon pad from a high-impedance (floating) input to a driven push-pull output capable of sourcing current. This single import line is the bridge between your Python script and the physical world, enabling everything from blinking an LED to triggering a 120V AC contactor via an optocoupler.
Core Translation: Software to Silicon Limits
Before writing a single line of Python, you must understand the physical constraints of the silicon you are controlling. The RPi.GPIO library does not enforce hardware limits; it will happily allow you to command a pin to output current until the physical trace melts or the SoC browns out. Below are the hard electrical limits for the Raspberry Pi 4 and earlier BCM-based boards.
| Parameter | Value | Engineering Notes & Edge Cases |
|---|---|---|
| VDD_IO (Logic Voltage) | 3.3V Nominal | Absolute max is 3.6V. A reading of 3.2V on a multimeter is normal under load; below 3.0V indicates a brownout or poor USB-C power supply. |
| Max Continuous Current (Per Pin) | 16mA | Applies to both sourcing (current out) and sinking (current to ground). Exceeding this degrades the pin's output transistor over time. |
| Total Bank Current Limit | 50mA | The sum of all active GPIO pins on the 3.3V rail must not exceed 50mA. You cannot run three 16mA LEDs simultaneously. |
| Logic HIGH Threshold | > 1.3V | When reading an input, any voltage above 1.3V is registered as GPIO.HIGH (1). |
| Logic LOW Threshold | < 1.3V | Any voltage below 1.3V is registered as GPIO.LOW (0). The gap between 0.8V and 1.3V is an undefined transition zone. |
| Internal Pull-up/Pull-down | ~50kΩ to 65kΩ | These are weak internal resistors. If your external circuit has a lower impedance, the internal pull state will be overridden. |
The Great Numbering Confusion: BCM vs. BOARD
The most common point of failure for beginners using RPi.GPIO as GPIO is the numbering scheme. The library requires you to explicitly declare how you want to address the pins using GPIO.setmode(). If you skip this, your script will throw a runtime error. If you choose the wrong one, you will toggle the wrong physical pin, potentially shorting a 3.3V output to a ground or 5V rail.
- BOARD Numbering (
GPIO.setmode(GPIO.BOARD)): Refers to the physical pin numbers printed on the board, from 1 to 40. Pin 1 is 3.3V, Pin 2 is 5V, Pin 6 is Ground. This is hardware-agnostic; it works the same on a Pi 3, Pi 4, and Pi 5. - BCM Numbering (
GPIO.setmode(GPIO.BCM)): Refers to the Broadcom SOC channel numbers. This is the internal silicon mapping. For example, Physical Pin 11 on the header is actually BCM GPIO 17. Physical Pin 12 is BCM GPIO 18.
gpiozero and Node-RED) default to BCM numbering. If you are mixing RPi.GPIO scripts with modern libraries, always use GPIO.setmode(GPIO.BCM) to maintain sanity across your codebase.
What People Commonly Confuse It With
Do not confuse RPi.GPIO with pigpio or gpiozero. RPi.GPIO is a low-level, procedural library that requires manual setup, teardown (GPIO.cleanup()), and state management. gpiozero is an object-oriented wrapper built on top of lower-level daemons that handles pin cleanup automatically and abstracts away the BCM/BOARD confusion. Furthermore, RPi.GPIO relies on software-timed PWM, which jitters under CPU load; if you need hardware-timed PWM for precise servo control, you must use the pigpio daemon instead.
Worked Numeric Example: Sizing a GPIO Current-Limiting Resistor
Let’s apply the hardware limits to a real circuit. You want to connect a standard 5mm red LED directly to BCM GPIO 17 (Physical Pin 11) using RPi.GPIO. You cannot wire the LED directly; the Pi will attempt to source infinite current, the LED will clamp the voltage, and the Pi's GPIO pin will burn out.
Known Variables:
- Pi GPIO Output Voltage (
V_s): 3.3V - Red LED Forward Voltage (
V_f): 2.0V (from datasheet) - Target LED Current (
I): 10mA (0.010A). We choose 10mA to stay safely below the 16mA absolute max, preserving the 50mA total bank limit for other pins.
The Calculation (Ohm's Law):
We need to drop the excess voltage across a resistor.
R = (V_s - V_f) / I
R = (3.3V - 2.0V) / 0.010A
R = 1.3V / 0.010A = 130Ω
Selecting the Real-World Component:
130Ω is not a standard E12 resistor value. We must round up to the next available value to ensure we do not exceed our 10mA target. The nearest standard E12 value is 150Ω.
Verifying Power Dissipation:
P = I² × R
P = (0.010)² × 150 = 0.0001 × 150 = 0.015W
A standard 1/4W (0.25W) through-hole resistor is more than adequate for this task. In your Python script, setting GPIO.output(17, GPIO.HIGH) will now safely illuminate the LED at 10mA.
Where You Meet This In Practice (And Where It Breaks)
You will encounter import RPi.GPIO as GPIO in almost every legacy home automation tutorial, HVAC relay controller, and basic sensor script. However, as hardware has evolved, the library's limitations have become glaringly obvious in modern deployments.
The Relay Driver Trap
A common mistake is trying to drive a 5V relay module directly from a Pi GPIO pin. A typical 5V relay coil requires 70mA to 90mA to energize. The Pi can only supply 16mA. If you wire this directly, the GPIO pin will sag to near 0V, the relay will chatter or fail to pull in, and the Pi may reboot due to voltage rail collapse. The fix: Use the GPIO pin to drive the base of an NPN transistor (like a 2N2222) or a logic-level MOSFET (like an IRLZ44N), which then switches the 5V relay coil using the Pi's 5V pin or an external power supply.
The Raspberry Pi 5 Architecture Shift
If you are deploying new hardware in 2026, you are likely using the Raspberry Pi 5. The Pi 5 abandoned the legacy BCM2711 SoC GPIO controller in favor of a dedicated RP1 southbridge chip. Because RPi.GPIO was hardcoded to interact with the memory addresses of the older Broadcom chips, the native RPi.GPIO library does not work on the Pi 5.
To run legacy RPi.GPIO scripts on a Pi 5, you must install the rpi-lgpio shim package, which intercepts the RPi.GPIO calls and translates them to the modern lgpio C library that understands the RP1 chip. For new projects on Pi 5, bypass RPi.GPIO entirely and use gpiozero, which automatically detects the hardware backend and handles the RP1 translation natively without code changes.
Frequently Asked Questions
Why do my GPIO pins trigger randomly on boot?
On boot, before your Python script runs and sets pin modes, all GPIO pins default to high-impedance inputs (floating). Electromagnetic interference or static can cause the pin to read as HIGH, triggering a connected relay. Always wire a 10kΩ external pull-down resistor between the GPIO pin and ground on critical circuits, or use a relay module with an optocoupler that requires a positive voltage to trigger.
Do I need to call GPIO.cleanup() every time?
Yes. If your script crashes or you exit without calling GPIO.cleanup(), the pins remain in their last state (e.g., driven HIGH). When you restart the script, RPi.GPIO will throw a warning that the pin is already in use, and it may refuse to reconfigure it. Wrap your main loop in a try...finally block to guarantee cleanup executes even on a keyboard interrupt (Ctrl+C).
Can I use RPi.GPIO for reading high-speed encoders?
No. RPi.GPIO relies on Python's software interrupts, which are subject to OS scheduling jitter. If a rotary encoder pulses faster than a few kilohertz, Python will miss the edges. For high-speed digital reads, use a dedicated hardware quadrature decoder chip or switch to the pigpio library, which runs a background daemon in C to capture hardware-timed interrupts with microsecond precision.
For exact physical pin layouts and BCM mappings across all Raspberry Pi models, always reference the interactive Pinout.xyz GPIO database before wiring a new circuit.
