How to enable i2c on the Raspberry Pi

Step 1

Enable i2c with raspi-config or config.txt

The friendly way:

sudo raspi-config
# Interface Options  →  I2C  →  Yes

Or the direct way — add one line to the boot config (Bookworm and later use /boot/firmware/config.txt; older releases use /boot/config.txt):

dtparam=i2c_arm=on

Reboot either way. The bus appears as /dev/i2c-1. (Both routes are documented in the official Raspberry Pi configuration docs, alongside every other config.txt option.)

Step 2

Verify with i2cdetect

sudo apt install i2c-tools
i2cdetect -y 1

With a sensor wired to GPIO2 (SDA, pin 3) and GPIO3 (SCL, pin 5), its address shows up in the grid — here's how to read the output, and the address list tells you what you're looking at. Nothing showing? The 7-step checklist finds it. One nicety: the Pi has 1.8 kΩ pull-ups soldered on those pins, so pull-up worries mostly don't apply.

To use the bus from Python without sudo:

sudo adduser $USER i2c   # then log out and back in

Reading the output

What the i2cdetect grid is telling you

The grid confuses people the first time, because it shows every address from 0x00 to 0x7F even though only 0x08–0x77 is usable. Three things can appear in a cell:

     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
00:                         -- -- -- -- -- -- -- --
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
30: -- -- -- -- -- -- -- -- -- -- -- -- 3c -- -- --
40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
60: -- -- -- -- -- -- -- -- UU -- -- -- -- -- -- --
70: -- -- -- -- -- -- 76 --

• A hex number (3c, 76) — a device answered. That's an address, not an identity: 0x76 is a BME280 or a BMP280 or a BME680, and the grid can't tell you which.
• -- — nobody answered. Normal for the vast majority of cells.
• UU — a kernel driver already owns that address, so i2cdetect skipped it rather than interfere. This is good news, not an error: something's there and it's bound to a driver (a hardware RTC, once you've loaded its overlay). The catch is that your own script can't talk to that address directly any more — the driver has it, and you go through the driver instead.

The empty run at the start of row 00: and the short row 70: aren't bugs — those are the reserved ranges the spec keeps, so i2cdetect doesn't probe them.

Beyond detect

Read a register without writing any code

i2c-tools ships three more commands that most tutorials never mention, and they're the fastest way to prove a sensor works before you write a line of Python:

# read one register: bus 1, device 0x76, register 0xD0 (BME280 chip-ID)
i2cget -y 1 0x76 0xD0
# -> 0x60   (0x60 = BME280, 0x58 = BMP280 — you just identified the chip)

# dump every register on the device
i2cdump -y 1 0x76

# write a byte: bus 1, device 0x76, register 0xF4, value 0x27
i2cset -y 1 0x76 0xF4 0x27

i2cget is genuinely the fastest chip-ID check there is — one command tells you whether the "BME280" you bought is really a BMP280, which is the single most common substitution on the market. Careful with i2cset, though: it writes real registers, and a wrong value can put a device into an odd mode until you power-cycle it.

From Python

Reading an i2c sensor from Python with smbus2

With the bus enabled and your user in the i2c group, smbus2 is the usual route:

pip install smbus2

from smbus2 import SMBus

with SMBus(1) as bus:                      # /dev/i2c-1
    chip_id = bus.read_byte_data(0x76, 0xD0)
    print(hex(chip_id))                    # 0x60 -> BME280

    # multi-byte read: 3 bytes starting at 0xF7
    data = bus.read_i2c_block_data(0x76, 0xF7, 3)
    print([hex(b) for b in data])

If that raises PermissionError, the group change hasn't taken effect — log out and back in. If it raises OSError: [Errno 121] Remote I/O error, nothing ACKed at that address: the device isn't there, isn't powered, or is at a different address than you think. Run i2cdetect again and trust the grid over the datasheet.

More buses

A second i2c bus on the Pi with dtoverlay=i2c-gpio

Two sensors with the same fixed address and no jumper? You don't have to buy a multiplexer — the Pi can bit-bang a second bus on any two spare GPIOs:

# /boot/firmware/config.txt
dtoverlay=i2c-gpio,bus=3,i2c_gpio_sda=23,i2c_gpio_scl=24

After a reboot that appears as /dev/i2c-3, and i2cdetect -y 3 scans it. Put the clashing device there and the conflict disappears — at the cost of two GPIOs and some CPU, since the kernel is toggling the lines in software rather than using dedicated hardware.

That software driver has a bonus: it honours clock stretching correctly, which the Pi's hardware controller famously doesn't. If a CCS811 or BME680 is giving you corrupt reads, moving it to an i2c-gpio bus fixes both problems at once. Remember these GPIOs have no pull-up resistors — unlike GPIO2/3, which have the Pi's 1.8 kΩ pair fitted — so the device's own breakout must provide them, or you add your own.

Step 3 (optional)

Raspberry Pi i2c speed, and the one Pi gotcha

The default clock is 100 kHz. For Fast-mode devices:

dtparam=i2c_arm=on,i2c_arm_baudrate=400000

The gotcha: the Pi's hardware controller has a long-standing clock-stretching bug. Most sensors never stretch and never notice — but if yours does (CCS811, BME680), you'll see corrupted reads that no rewiring fixes. The workarounds live in that article. Ready to populate the bus? Start with the best i2c sensors for the Pi.