smbus2

smbus2 is a pure-Python, drop-in replacement for the python-smbus / python3-smbus Linux SMBus bindings. It wraps the Linux kernel’s I2C/SMBus ioctl interface directly — no C extension required — and extends the familiar smbus API with additional functionality such as combined read/write transactions (i2c_rdwr) and Packet Error Checking (PEC).

Getting Started

• Introduction
  • What is smbus2?
  • Goals
  • Platform Support
  • Checking the Installed Version
  • Tested Python Versions
  • Supported Hardware
  • Supported SMBus / I2C Operations
  • Relationship to python-smbus
  • Further Reading
• Installation
  • System Prerequisites
  • From PyPI
  • From conda-forge
  • From Source
  • Verifying the Installation

Using smbus2

• Operations
  • Opening and Closing the Bus
  • SMBus Read Operations
  • SMBus Write Operations
  • Combined Transactions with i2c_rdwr
  • PEC — Packet Error Checking
  • Querying Adapter Capabilities
  • Process Call and Block Process Call
• Best Practices
  • Always Use the Context Manager
  • Do Not Create Multiple SMBus Instances for the Same Bus
  • Prefer i2c_rdwr for Devices That Do Not Use the Register-Address Protocol
  • Use i2c_rdwr to Bypass the 32-Byte SMBus Limit
  • Add Small Delays Between Operations on Slow Devices
  • Prefer write_byte / read_byte for Devices With No Register Concept
  • Handle OSError Gracefully
• Tips and Tricks
  • Signed Integer Conversion
  • Endianness / Byte-Order Conversion
  • Reading Devices That Have No Register Address
  • Write-Then-Read (Repeated Start)
  • Checking Adapter Capabilities
  • Sharing the Bus Across Multiple Modules
  • asyncio / Async Support
  • Setting I2C Bus Clock Speed (Baud Rate)

Support

• Troubleshooting
  • OSError: [Errno 121] Remote I/O error
  • OSError: [Errno 5] Input/output error
  • ModuleNotFoundError: No module named 'fcntl'
  • SystemError: buffer overflow (Python 3.14+)
  • Reads Return Unexpected Values or Incorrect Data
  • Very Slow Reads (read_byte_data, read_i2c_block_data)
• FAQ
  • Does smbus2 work on Windows or macOS?
  • Can I read or write more than 32 bytes at once?
  • How do I perform a repeated start (write then read without STOP)?
  • Can I use 10-bit I2C addresses?
  • Why does my device not respond when I use read_byte_data or write_byte_data?
  • Can I use smbus2 with asyncio?
  • How do I set the I2C clock speed?
  • Can I open multiple SMBus instances for the same bus in one process?
  • How do I convert a raw unsigned value to a signed integer?
  • Where is the API documentation?

Reference

• API Reference
  • SMBus
  • i2c_msg
  • I2cFunc
• References
  • SMBus and I²C Specifications
  • Linux Kernel I2C / SMBus Documentation
  • Linux Kernel Header Files
  • i2c-tools User-Space Utilities
  • Python ctypes and struct References
  • smbus2 Project Resources