modbus-rs (Python)

Fast Modbus TCP + Serial bindings for Python, powered by Rust.

PyPI package: modbus-rs
Import name: modbus_rs

Licensing

This package is available under GNU GPL v3.0 for open-source use.

Commercial licenses are also available for proprietary/closed-source use. Contact: ch.raghava44@gmail.com

Install

pip install modbus-rs

Quick Start

Example codes: modbus-rs/blob/main/mbus-ffi/python/examples

Synchronous TCP client

import modbus_rs

with modbus_rs.TcpTransport.connect("192.168.1.10", port=502) as transport:
    client = transport.create_client(unit_id=1)
    regs = client.read_holding_registers(0, 10)
    print(regs)

Async TCP client

import asyncio
import modbus_rs

async def main():
    async with await modbus_rs.AsyncTcpTransport.connect("192.168.1.10") as transport:
        client = transport.create_client(unit_id=1)
        regs = await client.read_holding_registers(0, 10)
        print(regs)

asyncio.run(main())

Serial client (RTU)

import modbus_rs

with modbus_rs.RtuTransport.open("/dev/ttyUSB0", baud_rate=9600) as transport:
    client = transport.create_client(unit_id=1)
    regs = client.read_holding_registers(0, 5)
    print(regs)

Async TCP server

import asyncio
import modbus_rs

class MyApp(modbus_rs.ModbusApp):
    def handle_read_holding_registers(self, address, count):
        return [address + i for i in range(count)]

async def main():
    server = modbus_rs.AsyncTcpServer("0.0.0.0", MyApp(), port=5020, unit_id=1)
    await server.serve_forever()

asyncio.run(main())

Exceptions

ModbusError
ModbusTimeout
ModbusConnectionError
ModbusProtocolError
ModbusDeviceException
ModbusConfigError
ModbusInvalidArgument

Build and Test Locally

To develop the Python bindings locally, create a virtual environment, activate it, build the bindings using Maturin, and run the tests.

1) Set up a virtual environment

Create a Python virtual environment at the repository root to isolate dependencies:

# Create the virtual environment
python3 -m venv .venv

# Activate the virtual environment
# On macOS / Linux:
source .venv/bin/activate
# On Windows (Command Prompt):
.venv\Scripts\activate.bat
# On Windows (PowerShell):
.venv\Scripts\Activate.ps1

Once activated, your terminal prompt will be prefixed with (.venv). To deactivate the virtual environment when you are done, run:

deactivate

2) Install build/test dependencies

pip install --upgrade pip
pip install maturin pytest pytest-asyncio

3) Compile and install the bindings in development mode

From the repository root, change to the mbus-ffi directory and compile the package.

The Python bindings features are modular:

python-client — Enables Modbus client transports and clients.
python-server — Enables Modbus server classes and apps.
python-gateway — Enables TCP gateway classes (requires python-client).
python-full — Convenience alias that enables all client, server, and gateway features.

To compile with all features enabled:

cd mbus-ffi
maturin develop --features python-full

4) Run Python tests

Run pytest:

pytest tests/python/ -v

Run Python Examples

The examples live in this repository under mbus-ffi/python/examples/. Before running them, make sure your virtual environment is activated and the extension is built.

1) Build/install the extension from source

Ensure you are in the repository root, activate the virtual environment, and compile the package:

source .venv/bin/activate   # or Windows equivalent
cd mbus-ffi
maturin develop --features python-full

2) Start the example server (terminal 1)

Run the server from the repository root (make sure the virtual environment is active):

source .venv/bin/activate
cd mbus-ffi/python/examples/python_server
python3 python_server.py --host 127.0.0.1 --port 5020 --unit-id 1

3) Run the sync client (terminal 2)

Run the client from the repository root:

source .venv/bin/activate
cd mbus-ffi/python/examples/python_client
python3 python_client.py --host 127.0.0.1 --port 5020 --unit-id 1

4) Run the async client (terminal 2)

Run the async client from the repository root:

source .venv/bin/activate
cd mbus-ffi/python/examples/python_async_client
python3 async_client.py --host 127.0.0.1 --port 5020 --unit-id 1

5) Run multi-unit examples (terminal 2)

Verify the new transport/client split by running one of the multi-unit/transport examples from the repository root:

source .venv/bin/activate
cd mbus-ffi/python/examples
python3 11-tcp-transport-multi-unit.py --host 127.0.0.1 --port 5020

Optional: multi-server async demo

Start 3 servers on ports 5020, 5021, and 5022, then run:

source .venv/bin/activate
cd mbus-ffi/python/examples/python_async_client
python3 async_client.py --host 127.0.0.1 --port 5020 --multi

Modbus TCP Gateway (`python-gateway` feature)

The python-gateway feature exposes a thread-safe sync gateway and an asyncio-friendly async gateway that forward inbound Modbus/TCP requests to one or more downstream Modbus/TCP servers based on a unit-id routing table.

Build with the gateway feature enabled (or use the complete python-full suite):

cd mbus-ffi
maturin develop --features python-client,python-gateway

Sync gateway

import modbus_rs

gw = modbus_rs.TcpGateway("0.0.0.0:5020")
ch = gw.add_tcp_downstream("192.168.1.10", 502)
gw.add_unit_route(unit=1, channel=ch)
gw.serve_forever()  # blocks; call gw.stop() from another thread to exit

Async gateway

import asyncio
import modbus_rs

async def main():
    gw = modbus_rs.AsyncTcpGateway("0.0.0.0:5020")
    ch = gw.add_tcp_downstream("192.168.1.10", 502)
    gw.add_unit_route(unit=1, channel=ch)
    await gw.serve_forever()  # cancel the task or call gw.stop() to exit

asyncio.run(main())

Note: The optional event_handler= constructor argument accepts a GatewayEventHandler subclass to receive telemetry callbacks for routing, forwarding, and errors. See event_handler_demo.py for a complete example of logging telemetry events.

Migration Guide

Detailed step-by-step migration guides are available in the Migration Guides directory.

More Docs

Project docs: documentation/python_bindings.md
Full crate README (C/WASM/Python): mbus-ffi/README.md

License

This project is licensed under GNU GPL v3.0. See LICENSE for details.

Commercial licenses for proprietary use are available via ch.raghava44@gmail.com.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

modbus_rs-0.16.0.tar.gz (5.3 MB view details)

Uploaded Jul 30, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

modbus_rs-0.16.0-cp311-cp311-win_amd64.whl (479.4 kB view details)

Uploaded Jul 30, 2026 CPython 3.11Windows x86-64

modbus_rs-0.16.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (627.3 kB view details)

Uploaded Jul 30, 2026 CPython 3.11manylinux: glibc 2.17+ x86-64

modbus_rs-0.16.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (663.4 kB view details)

Uploaded Jul 30, 2026 CPython 3.11manylinux: glibc 2.17+ ARM64

modbus_rs-0.16.0-cp311-cp311-macosx_11_0_arm64.whl (536.1 kB view details)

Uploaded Jul 30, 2026 CPython 3.11macOS 11.0+ ARM64

modbus_rs-0.16.0-cp311-cp311-macosx_10_12_x86_64.whl (518.9 kB view details)

Uploaded Jul 30, 2026 CPython 3.11macOS 10.12+ x86-64

File details

Details for the file modbus_rs-0.16.0.tar.gz.

File metadata

Download URL: modbus_rs-0.16.0.tar.gz
Upload date: Jul 30, 2026
Size: 5.3 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for modbus_rs-0.16.0.tar.gz
Algorithm	Hash digest
SHA256	`0e482e68dff4719be93fcc85adcb481a7797e7b3922f38b00578b8962c640aec`
MD5	`17db324f2b2b720c0f833e873dabf56a`
BLAKE2b-256	`0f6e59e47072eff9cb2005c4811064680aa72ac974285b5b81f6fa353f31c15d`

See more details on using hashes here.

Provenance

The following attestation bundles were made for modbus_rs-0.16.0.tar.gz:

Publisher: release-python.yml on Raghava-Ch/modbus-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: modbus_rs-0.16.0.tar.gz
- Subject digest: 0e482e68dff4719be93fcc85adcb481a7797e7b3922f38b00578b8962c640aec
- Sigstore transparency entry: 2288000420
- Sigstore integration time: Jul 30, 2026
Source repository:
- Permalink: Raghava-Ch/modbus-rs@1e50f8dc97d2f17f305712bd6e48e10ff619b33c
- Branch / Tag: refs/tags/py-v0.16.0
- Owner: https://github.com/Raghava-Ch
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release-python.yml@1e50f8dc97d2f17f305712bd6e48e10ff619b33c
- Trigger Event: push

File details

Details for the file modbus_rs-0.16.0-cp311-cp311-win_amd64.whl.

File metadata

Download URL: modbus_rs-0.16.0-cp311-cp311-win_amd64.whl
Upload date: Jul 30, 2026
Size: 479.4 kB
Tags: CPython 3.11, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for modbus_rs-0.16.0-cp311-cp311-win_amd64.whl
Algorithm	Hash digest
SHA256	`8f4c77d15b5750e920ab5a6eef1f08016d2f1e1de28fd57fd299302ddf0907da`
MD5	`67d00f7c5f5e7dca108194f873f7a768`
BLAKE2b-256	`46b174e8789f2fc4fde3b50c47755cd1abf6d4fc7ec7538b1de83f030d5c07cf`

See more details on using hashes here.

Provenance

The following attestation bundles were made for modbus_rs-0.16.0-cp311-cp311-win_amd64.whl:

Publisher: release-python.yml on Raghava-Ch/modbus-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: modbus_rs-0.16.0-cp311-cp311-win_amd64.whl
- Subject digest: 8f4c77d15b5750e920ab5a6eef1f08016d2f1e1de28fd57fd299302ddf0907da
- Sigstore transparency entry: 2288000464
- Sigstore integration time: Jul 30, 2026
Source repository:
- Permalink: Raghava-Ch/modbus-rs@1e50f8dc97d2f17f305712bd6e48e10ff619b33c
- Branch / Tag: refs/tags/py-v0.16.0
- Owner: https://github.com/Raghava-Ch
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release-python.yml@1e50f8dc97d2f17f305712bd6e48e10ff619b33c
- Trigger Event: push

File details

Details for the file modbus_rs-0.16.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: modbus_rs-0.16.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Jul 30, 2026
Size: 627.3 kB
Tags: CPython 3.11, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for modbus_rs-0.16.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`bcdca6da95e632de9a33e11cf73763d5d72b4aadde9dea2751e2ecd85752f742`
MD5	`5d0178a762ca3a52193a27cd5cd3a413`
BLAKE2b-256	`b3311f38bc217e975a395156a88642bbbfa49fea46f36a8c553dce4ab80992e0`

See more details on using hashes here.

Provenance

The following attestation bundles were made for modbus_rs-0.16.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release-python.yml on Raghava-Ch/modbus-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: modbus_rs-0.16.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Subject digest: bcdca6da95e632de9a33e11cf73763d5d72b4aadde9dea2751e2ecd85752f742
- Sigstore transparency entry: 2288000617
- Sigstore integration time: Jul 30, 2026
Source repository:
- Permalink: Raghava-Ch/modbus-rs@1e50f8dc97d2f17f305712bd6e48e10ff619b33c
- Branch / Tag: refs/tags/py-v0.16.0
- Owner: https://github.com/Raghava-Ch
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release-python.yml@1e50f8dc97d2f17f305712bd6e48e10ff619b33c
- Trigger Event: push

File details

Details for the file modbus_rs-0.16.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

Download URL: modbus_rs-0.16.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Upload date: Jul 30, 2026
Size: 663.4 kB
Tags: CPython 3.11, manylinux: glibc 2.17+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for modbus_rs-0.16.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm	Hash digest
SHA256	`9c4f32b36d878e2ff513b38e8fe550942a5d9bc0352d20e3d15072f08800368a`
MD5	`9f78d67ebc9103f97a419027f796ccbc`
BLAKE2b-256	`237f2b5f6f28db7a6feaaf04b60e3c72aad8131c282235d884a34f905e84e56b`

See more details on using hashes here.

Provenance

The following attestation bundles were made for modbus_rs-0.16.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release-python.yml on Raghava-Ch/modbus-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: modbus_rs-0.16.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
- Subject digest: 9c4f32b36d878e2ff513b38e8fe550942a5d9bc0352d20e3d15072f08800368a
- Sigstore transparency entry: 2288000659
- Sigstore integration time: Jul 30, 2026
Source repository:
- Permalink: Raghava-Ch/modbus-rs@1e50f8dc97d2f17f305712bd6e48e10ff619b33c
- Branch / Tag: refs/tags/py-v0.16.0
- Owner: https://github.com/Raghava-Ch
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release-python.yml@1e50f8dc97d2f17f305712bd6e48e10ff619b33c
- Trigger Event: push

File details

Details for the file modbus_rs-0.16.0-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

Download URL: modbus_rs-0.16.0-cp311-cp311-macosx_11_0_arm64.whl
Upload date: Jul 30, 2026
Size: 536.1 kB
Tags: CPython 3.11, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for modbus_rs-0.16.0-cp311-cp311-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`14b1bb3ce7adb8e1f7a0a2633b9be8af10d4afd27b2be11250bb85d852107de7`
MD5	`6de33a78c88101ed10a68bfc01c3ada7`
BLAKE2b-256	`15995be7700e9f8b7e7c923a7a3ec6a2827fc9aa569cc1ebad8555237e96c3d7`

See more details on using hashes here.

Provenance

The following attestation bundles were made for modbus_rs-0.16.0-cp311-cp311-macosx_11_0_arm64.whl:

Publisher: release-python.yml on Raghava-Ch/modbus-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: modbus_rs-0.16.0-cp311-cp311-macosx_11_0_arm64.whl
- Subject digest: 14b1bb3ce7adb8e1f7a0a2633b9be8af10d4afd27b2be11250bb85d852107de7
- Sigstore transparency entry: 2288000569
- Sigstore integration time: Jul 30, 2026
Source repository:
- Permalink: Raghava-Ch/modbus-rs@1e50f8dc97d2f17f305712bd6e48e10ff619b33c
- Branch / Tag: refs/tags/py-v0.16.0
- Owner: https://github.com/Raghava-Ch
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release-python.yml@1e50f8dc97d2f17f305712bd6e48e10ff619b33c
- Trigger Event: push

File details

Details for the file modbus_rs-0.16.0-cp311-cp311-macosx_10_12_x86_64.whl.

File metadata

Download URL: modbus_rs-0.16.0-cp311-cp311-macosx_10_12_x86_64.whl
Upload date: Jul 30, 2026
Size: 518.9 kB
Tags: CPython 3.11, macOS 10.12+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for modbus_rs-0.16.0-cp311-cp311-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`cdfcc4d42191bf6bb7f2d691942d26da82461cc9fc681c77712a7625398649e3`
MD5	`34edceedece30efded9413cdea902e20`
BLAKE2b-256	`37fc2818b13a2d71e6925b2ab48f4ed49f016aff534e10317d716e8dbc696e71`

See more details on using hashes here.

Provenance

The following attestation bundles were made for modbus_rs-0.16.0-cp311-cp311-macosx_10_12_x86_64.whl:

Publisher: release-python.yml on Raghava-Ch/modbus-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: modbus_rs-0.16.0-cp311-cp311-macosx_10_12_x86_64.whl
- Subject digest: cdfcc4d42191bf6bb7f2d691942d26da82461cc9fc681c77712a7625398649e3
- Sigstore transparency entry: 2288000517
- Sigstore integration time: Jul 30, 2026
Source repository:
- Permalink: Raghava-Ch/modbus-rs@1e50f8dc97d2f17f305712bd6e48e10ff619b33c
- Branch / Tag: refs/tags/py-v0.16.0
- Owner: https://github.com/Raghava-Ch
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release-python.yml@1e50f8dc97d2f17f305712bd6e48e10ff619b33c
- Trigger Event: push

Release history Release notifications | RSS feed

This release

0.16.0

Jul 30, 2026

0.15.2

Jun 28, 2026

0.15.0

Jun 20, 2026

0.14.0

Jun 6, 2026

0.13.0

Jun 2, 2026

0.12.0

May 27, 2026

0.11.0

May 23, 2026

0.10.0

May 15, 2026

0.8.0

Apr 26, 2026

modbus-rs 0.16.0

modbus-rs (Python)

Licensing

Install

Quick Start

Synchronous TCP client

Async TCP client

Serial client (RTU)

Async TCP server

Exceptions

Build and Test Locally

1) Set up a virtual environment

2) Install build/test dependencies

3) Compile and install the bindings in development mode

4) Run Python tests

Run Python Examples

1) Build/install the extension from source

2) Start the example server (terminal 1)

3) Run the sync client (terminal 2)

4) Run the async client (terminal 2)

5) Run multi-unit examples (terminal 2)

Optional: multi-server async demo

Modbus TCP Gateway (python-gateway feature)

Sync gateway

Async gateway

Migration Guide

More Docs

License

Project links

Key dates

1 maintainer

GitHub Statistics

License

Requires

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed

Modbus TCP Gateway (`python-gateway` feature)