Installation

Install PyModbus with pip or conda on Windows, Linux, and macOS. Includes serial extras for RTU, virtual environments, and verification steps.

Install PyModbus and verify it works.

Quick Install

pip install pymodbus

For Modbus RTU over serial, add the serial extra:

pip install pymodbus[serial]

Installation Methods

# Basic install
pip install pymodbus

# With serial support (for RTU/ASCII)
pip install pymodbus[serial]

# All optional dependencies
pip install pymodbus[all]

conda install -c conda-forge pymodbus

# Ubuntu/Debian
sudo apt install python3-pymodbus

# Fedora
sudo dnf install python3-pymodbus

# Arch
sudo pacman -S python-pymodbus

Virtual Environment

python -m venv modbus-env
source modbus-env/bin/activate   # Linux/macOS
# modbus-env\Scripts\activate    # Windows

pip install pymodbus[serial]

Platform Setup

Linux Serial Permissions

For RTU over serial, your user needs access to serial ports:

sudo usermod -a -G dialout $USER
# Log out and back in for the group change to take effect

macOS USB-to-Serial Drivers

If you use a USB-to-serial adapter for RTU, install the driver for your chip:

FTDI: FTDI drivers
CP210x: Silicon Labs drivers
CH340: WCH drivers

List available serial ports:

ls /dev/cu.* /dev/tty.*

Windows Serial (RTU)

pip install pymodbus[serial]

Check Device Manager for your COM port number (e.g., COM3).

Verify Installation

import pymodbus
from pymodbus.client import ModbusTcpClient

print(f"PyModbus version: {pymodbus.__version__}")

# Verify TCP client import works
client = ModbusTcpClient('127.0.0.1')
print("TCP client: OK")

# Verify serial client import (requires pymodbus[serial])
try:
    from pymodbus.client import ModbusSerialClient
    print("Serial client: OK")
except ImportError:
    print("Serial client: not installed (run pip install pymodbus[serial])")

python test_pymodbus.py

Log Modbus data automatically

TofuPilot records test results from your PyModbus scripts, tracks pass/fail rates, and generates compliance reports. Free to start.

Common Issues

ModuleNotFoundError

ModuleNotFoundError: No module named 'pymodbus' means pip installed into a different Python than you're running.

# Check which Python is active
which python
python --version

# Install for the correct Python
python -m pip install pymodbus

Serial Port Permission Denied (Linux)

SerialException: could not open port usually means your user is not in the dialout group. See Linux Serial Permissions above.

Connection Refused (TCP)

ConnectionRefusedError: [Errno 111] Connection refused means the device is not listening on that IP/port.

Verify the device IP address and port (default 502)
Check firewall rules
Test with: telnet 192.168.1.100 502

Dependencies

Dependency	Purpose	Install
Python 3.8+	Runtime	Required
pyserial	RTU/ASCII serial	`pip install pymodbus[serial]`
asyncio	Async client/server	Included in Python 3.7+

Specific Versions

# Pin a version
pip install pymodbus==3.5.0

# Install from source
pip install git+https://github.com/pymodbus-dev/pymodbus.git

Installation

On this page