Installing PyModbus
Complete PyModbus installation guide for Windows, Linux, and macOS. pip, conda, Docker, and troubleshooting tips included.
Install PyModbus on any platform with these step-by-step guides.
Quick Install
Just want to get started? Run pip install pymodbus and you're ready to go on most systems.
pip install pymodbusInstallation Methods
Using pip (Recommended)
# Install latest stable version
pip install pymodbus# Install with serial support
pip install pymodbus[serial]
# Install with all optional dependencies
pip install pymodbus[all]
# Install with specific extras
pip install pymodbus[serial,simulator]# Install development version
pip install git+https://github.com/pymodbus-dev/pymodbus.git
# Install in editable mode for development
git clone https://github.com/pymodbus-dev/pymodbus.git
cd pymodbus
pip install -e .Using conda
# Install from conda-forge
conda install -c conda-forge pymodbus
# Create new environment with PyModbus
conda create -n modbus-env python=3.9 pymodbus
conda activate modbus-envSystem Package Managers
sudo apt update
sudo apt install python3-pymodbus# Fedora
sudo dnf install python3-pymodbus
# RHEL/CentOS
sudo yum install python3-pymodbussudo pacman -S python-pymodbusPlatform-Specific Setup
Windows Setup
Install PyModbus
pip install pymodbusInstall Serial Support (for RTU)
If you need Modbus RTU over serial:
pip install pymodbus[serial]Verify Installation
import pymodbus
print(f"PyModbus version: {pymodbus.__version__}")
# Test TCP client
from pymodbus.client import ModbusTcpClient
client = ModbusTcpClient('127.0.0.1')
print("✓ PyModbus imported successfully")Linux Setup
Install PyModbus
# Using pip
pip install pymodbus
# Or using system package manager
sudo apt install python3-pymodbus # Ubuntu/DebianSerial Port Permissions (for RTU)
For Modbus RTU over serial, configure port permissions:
# Add user to dialout group (logout/login required)
sudo usermod -a -G dialout $USER
# Or set temporary permissions
sudo chmod 666 /dev/ttyUSB0Install Dependencies
# For serial support
pip install pyserial
# For async support
pip install asynciomacOS Setup
Install PyModbus
pip3 install pymodbusInstall Serial Driver (for USB adapters)
For USB-to-serial adapters, install appropriate drivers:
- FTDI chips: Install FTDI drivers
- CP210x chips: Install Silicon Labs drivers
- CH340 chips: Install CH340 drivers
Verify Serial Ports
# List available ports
ls /dev/cu.* /dev/tty.*Virtual Environments
Using venv
# Create virtual environment
python -m venv modbus-project
# Activate environment
source modbus-project/bin/activate # Linux/macOS
modbus-project\Scripts\activate # Windows
# Install PyModbus
pip install pymodbusUsing conda
# Create conda environment
conda create -n modbus-env python=3.9
# Activate environment
conda activate modbus-env
# Install PyModbus
conda install -c conda-forge pymodbusVerification
Test that PyModbus is working correctly:
# test_pymodbus.py
import pymodbus
from pymodbus.client import ModbusTcpClient, ModbusSerialClient
print(f"PyModbus version: {pymodbus.__version__}")
# Test TCP client creation
try:
tcp_client = ModbusTcpClient('127.0.0.1')
print("✓ TCP client support available")
except Exception as e:
print(f"✗ TCP client error: {e}")
# Test Serial client creation (if serial installed)
try:
serial_client = ModbusSerialClient('/dev/ttyUSB0')
print("✓ Serial client support available")
except Exception as e:
print(f"✗ Serial client error: {e}")
print("\nPyModbus installation verified!")Run the test:
python test_pymodbus.pyExpected output:
PyModbus version: 3.5.0
✓ TCP client support available
✓ Serial client support available
PyModbus installation verified!Common Issues
ModuleNotFoundError
Error: ModuleNotFoundError: No module named 'pymodbus'
Wrong Environment
PyModbus installed in different environment
Python Version
Using different Python version
Solution:
# Check current Python
which python
python --version
# Install for correct Python
python -m pip install pymodbusSerial Port Issues
Error: SerialException: could not open port
Solution for Linux:
# Add user to dialout group
sudo usermod -a -G dialout $USER
# Logout and login again
# Check port permissions
ls -l /dev/ttyUSB0Solution for Windows:
# Check Device Manager for COM port number
# Use correct port like 'COM3' not '/dev/ttyUSB0'Connection Refused
Error: ConnectionRefusedError: [Errno 111] Connection refused
Solutions:
- Verify device IP address and port (default 502)
- Check firewall settings
- Ensure Modbus device is powered and connected
- Test with telnet:
telnet 192.168.1.100 502
Docker Installation
Dockerfile
FROM python:3.9-slim
# Install PyModbus
RUN pip install pymodbus[all]
# For serial support in container
RUN apt-get update && apt-get install -y \
udev \
&& rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY . .
CMD ["python", "app.py"]Running with Docker
# Build image
docker build -t modbus-app .
# Run with network access (TCP)
docker run --network host modbus-app
# Run with serial device access (RTU)
docker run --device=/dev/ttyUSB0 modbus-appAdvanced Installation
From Source
# Clone repository
git clone https://github.com/pymodbus-dev/pymodbus.git
cd pymodbus
# Install in development mode
pip install -e .[all]
# Run tests
pytestSpecific Versions
# Install specific version
pip install pymodbus==3.5.0
# Install pre-release
pip install --pre pymodbusDependencies
Core Dependencies
- Python 3.8+
- No external dependencies for basic TCP
Optional Dependencies
- pyserial: For Modbus RTU/ASCII (serial communication)
- asyncio: For async client/server (included in Python 3.7+)
- click: For CLI tools
- prompt_toolkit: For REPL interface
Install all optional dependencies:
pip install pymodbus[all]Next Steps
Quick Start
Make your first Modbus connection
TCP Client
Connect to Modbus TCP devices
RTU Client
Serial communication setup
Basic Concepts
Understand Modbus fundamentals
Installation Complete! PyModbus is ready for industrial communication.
Quick Test
from pymodbus.client import ModbusTcpClient
# Test connection to local simulator
client = ModbusTcpClient('127.0.0.1', port=5020)
if client.connect():
print("✓ Successfully connected to Modbus device")
result = client.read_holding_registers(0, 1)
print(f"✓ Read test: {result}")
client.close()
else:
print("✗ Could not connect - is a Modbus server running?")How is this guide?
