Install & Compatibility
Where this runs
tested against v0.6.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.010s · 17.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.020s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SMBus
✓ from smbus2 import SMBus
SMBusWrapper
✓ from smbus2 import SMBus
✗ from smbus2 import SMBusWrapper
The SMBusWrapper class was deprecated and removed in version 0.4.0. Users should now instantiate SMBus directly.
i2c_msg
✓ from smbus2 import i2c_msg
Used for combined read/write transactions with SMBus.i2c_rdwr().
This quickstart demonstrates basic I2C read and write operations using the `SMBus` class with a context manager, ensuring proper resource cleanup. It also shows how to set I2C bus, device address, and register address, with placeholders for actual values and environment variables for safer execution.
import os
from smbus2 import SMBus
# Example: Read a byte from an I2C device (e.g., at address 0x27, register 0x00)
# Replace `1` with the correct I2C bus number for your system (e.g., 0 for older Raspberry Pis, 1 for newer)
# Replace `0x27` with your device's I2C address
# Replace `0x00` with the register to read from
I2C_BUS_NUMBER = int(os.environ.get('I2C_BUS_NUMBER', '1')) # Default to bus 1
DEVICE_ADDRESS = int(os.environ.get('I2C_DEVICE_ADDRESS', '0x27'), 16)
REGISTER_ADDRESS = int(os.environ.get('I2C_REGISTER_ADDRESS', '0x00'), 16)
try:
# Using 'with' statement ensures the bus is properly closed
with SMBus(I2C_BUS_NUMBER) as bus:
byte_data = bus.read_byte_data(DEVICE_ADDRESS, REGISTER_ADDRESS)
print(f"Read byte 0x{byte_data:02X} from device 0x{DEVICE_ADDRESS:02X}, register 0x{REGISTER_ADDRESS:02X} on bus {I2C_BUS_NUMBER}.")
# Example: Write a byte to the same device/register
write_value = 0xAA # Example value to write
bus.write_byte_data(DEVICE_ADDRESS, REGISTER_ADDRESS, write_value)
print(f"Written byte 0x{write_value:02X} to device 0x{DEVICE_ADDRESS:02X}, register 0x{REGISTER_ADDRESS:02X} on bus {I2C_BUS_NUMBER}.")
except FileNotFoundError:
print(f"Error: I2C bus {I2C_BUS_NUMBER} not found. Ensure I2C is enabled and the bus number is correct.")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingThe `SMBusWrapper` class was removed in version 0.4.0. Direct instantiation of `SMBus` should be used instead.fixReplace `from smbus2 import SMBusWrapper` with `from smbus2 import SMBus`, and update any `SMBusWrapper()` calls to `SMBus()`.
affects: >=0.4.0
gotchaFrequent consecutive block read/write operations, especially on Raspberry Pi Zero W, can lead to `[Errno 121] Remote I/O error`. This often indicates bus congestion or timing issues.fixIntroduce small delays between successive calls, or consider using the `SMBus.i2c_rdwr()` method for combined transactions, which uses repeated start bits instead of stop bits between transfers.
affects: All versions (hardware-dependent)
breakingVersion 0.6.0 fixed a buffer overflow issue that could occur when using Python 3.14 on 64-bit systems.fixUpgrade to smbus2 version 0.6.0 or newer to prevent potential buffer overflow issues.
affects: <0.6.0 with Python 3.14 (64-bit)
deprecatedTesting for Python 2.7, 3.4, and 3.5 was officially dropped in version 0.4.3. While the code might still function, these versions are no longer actively supported or tested.fixMigrate to Python 3.6 or newer for continued support and access to the latest smbus2 features and fixes.
affects: >=0.4.3
gotchasmbus2 is not a literal 'drop-in replacement' in terms of import statements for the original `smbus` (or `python-smbus`). Attempting `import smbus` when only `smbus2` is installed will result in a `ModuleNotFoundError`.fixAlways use `from smbus2 import SMBus` (or other smbus2 specific imports). The 'drop-in replacement' refers to API compatibility once the `SMBus` object is instantiated, not the module name itself.
affects: All versions
gotchaThe `force` parameter in many I2C/SMBus functions (e.g., `read_byte_data`) instructs the Linux kernel to reuse a slave address even if it's already in use by a driver. This can mask underlying hardware or driver configuration issues and should be used cautiously.fixOnly use `force=True` if you explicitly understand its implications and require it for specific scenarios. In most cases, if an address conflict occurs, it indicates a configuration problem that should be resolved at the system or driver level rather than bypassed with `force`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'smbus2'
The smbus2 package is not installed in the current Python environment.
OSError: [Errno 13] Permission denied
The current user lacks read/write permissions for the I2C device files, preventing access to the bus.
fixAdd your user to the `i2c` group (`sudo usermod -aG i2c $USER` and then log out/in or reboot) or run your script with `sudo`.
IOError: [Errno 2] No such file or directory: '/dev/i2c-1'
The specified I2C bus device file (e.g., `/dev/i2c-1`) does not exist because I2C is not enabled or the bus number is incorrect.
fixEnable I2C in your system configuration (e.g., using `sudo raspi-config` on Raspberry Pi) and verify the correct bus number (e.g., with `i2cdetect -l`).
OSError: [Errno 19] No such device
No I2C device responded at the specified address, indicating a wiring issue, incorrect address, or the device is not powered.
fixDouble-check wiring, ensure the I2C device is powered, and confirm the correct address using `i2cdetect -y <bus_number>`.
Upgrade
Version history
0.6.1latest on PyPI · released Apr 9, 2026
Audit
Dependencies
No dependency data recorded yet.