A modern Python Modbus library that is fully typed and well-tested.
Modbus is based on the master/slave communication pattern. We choose to use the terminology client and server instead, as it is more clear.
- Pure Python library with minimal dependencies
- Fully typed
- Full test coverage
- Support for Modbus TCP, RTU, ASCII and RTU-over-TCP clients
- Support for TCP over SSL connections
- Auto reconnect and retry functionality (which can be enabled optionally)
- Extensible with custom Modbus functions and exception codes
- Open source (BSD)
- Read coils (
0x01) - Read discrete inputs (
0x02) - Read holding registers (
0x03) - Read input registers (
0x04) - Write single coil (
0x05) - Write single register (
0x06) - Read exception status (
0x07) - Write multiple coils (
0x0F) - Write multiple registers (
0x10) - Report server ID (
0x11) - Read file record (
0x14) - Write file record (
0x15) - Mask write register (
0x16) - Read/write multiple registers (
0x17) - Read FIFO queue (
0x18) - Read device identification (
0x2B / 0x0E)
A simple example of an Async TCP client:
import asyncio
from tmodbus import create_async_tcp_client
async def main() -> None:
"""Show example of reading a Modbus register."""
async with create_async_tcp_client("127.0.0.1", 502, unit_id=1) as client:
response = await client.read_holding_registers(start_address=100, quantity=2)
print("Contents of holding registers 100 and 101: ", response)
if __name__ == "__main__":
asyncio.run(main())Various examples for Modbus RTU and TCP can be found in the examples folder.
async-serial
This library uses pyserial-asyncio-fast to access the serial port when using async RTU or ASCII.
Use pip install tmodbus[async-serial] to install.
This repository keeps a change log using GitHub's releases functionality. The format of the log is based on Keep a Changelog.
Releases are based on Semantic Versioning, and use the format
of MAJOR.MINOR.PATCH. In a nutshell, the version will be incremented
based on the following:
MAJOR: Incompatible or major changes.MINOR: Backwards-compatible new features and enhancements.PATCH: Backwards-compatible bugfixes and package updates.
This is an active open-source project. We are always open to people who want to use the code or contribute to it.
We've set up a separate document for our contribution guidelines.
Thank you for being involved! 😍
This Python project is fully managed using the uv dependency manager.
You need at least:
- Python 3.12+
- uv
To install all packages, including all development requirements:
uv sync --all-extras --devAs this repository uses the pre-commit framework, all changes are linted and tested with each commit. You can run all checks and tests manually, using the following command:
uv run pre-commit run --all-filesTo run just the Python tests:
uv run pytest