Introduction

What is smbus2?

smbus2 is a pure-Python library that provides access to Linux I2C and SMBus peripherals. It wraps the Linux kernel’s I2C character device interface (/dev/i2c-*) through ioctl system calls, using Python’s ctypes to map directly onto the kernel’s SMBus and I2C data structures. No compiled C extension is required — the package is 100% Python.

smbus2 was designed as a familiar drop-in replacement for the python-smbus / python3-smbus bindings that ship with many Linux distributions. The same method names are preserved so that existing code can be migrated by changing a single import line:

# Before
import smbus
bus = smbus.SMBus(1)

# After
import smbus2
bus = smbus2.SMBus(1)

Goals

Familiar API — provide the same interface as the original smbus Python package so that the migration cost for existing users is minimal.
Complete Linux I2C/SMBus functionality — expose features that the original bindings lack, including combined read/write transactions (i2c_rdwr), Packet Error Checking (PEC), and all standard SMBus commands.

Platform Support

smbus2 is a Linux-only library. It relies on the Linux kernel’s I2C subsystem and the /dev/i2c-N character devices that it exposes. The underlying ioctl calls and data structures (i2c_smbus_ioctl_data, i2c_rdwr_ioctl_data, etc.) are Linux-specific.

Checking the Installed Version

python -c "import smbus2; print(smbus2.__version__)"

Tested Python Versions

smbus2 currently targets Python 3.7 and later. Python 2.7 and 3.6 are no longer actively tested in CI (#128).

smbus2 v0.6.1 should still work on Python 2.7 through 3.6 as there are no intentional incompatibilities. Use at your own risk. Support and tagging for deprecated Python versions will be removed in the future.

Supported Hardware

Any Linux board or system that exposes an I2C adapter via /dev/i2c-N is supported. Common examples include:

Raspberry Pi (all models)
NVIDIA Jetson Nano / Xavier
BeagleBone Black / Green
Orange Pi, Rock Pi, and other Allwinner / Rockchip SBCs
Desktop / server systems with SMBus-capable chipsets
Any embedded Linux board with CONFIG_I2C_CHARDEV enabled in the kernel

Supported SMBus / I2C Operations

Operation	Method
Read byte (no register)	`read_byte`
Write byte (no register)	`write_byte`
Read byte from register	`read_byte_data`
Write byte to register	`write_byte_data`
Read word from register	`read_word_data`
Write word to register	`write_word_data`
Read I2C block	`read_i2c_block_data`
Write I2C block	`write_i2c_block_data`
Read SMBus block	`read_block_data`
Write SMBus block	`write_block_data`
Quick command	`write_quick`
Process call	`process_call`
Block process call	`block_process_call`
Combined write/read (repeated start)	`i2c_rdwr`
Packet Error Checking	`bus.pec`
Query adapter capabilities	`bus.funcs` / `I2cFunc`

Relationship to `python-smbus`

smbus2 is intended to be a drop-in replacement for python-smbus. All standard SMBus method names are identical. The only required change in existing code is the import statement (see example above). smbus2 additionally exposes i2c_rdwr, PEC support, I2cFunc capability flags, and named-bus support — features that are absent from python-smbus.