PySerial Documentation

Cross-platform Python library for serial port communication. Works with Arduino, Raspberry Pi, and industrial devices on Windows, Linux, macOS.

Cross-platform Python library for serial port access. Works everywhere Python does.

What is PySerial? Cross-platform Python library providing consistent serial port access on Windows, Linux, and macOS. Connect to Arduino, GPS modules, industrial devices, and any serial equipment.

Why PySerial?

Cross-Platform

Same API on Windows, Linux, and macOS

Battle-Tested

In production since 2001, actively maintained

Simple API

Easy to learn, powerful to use

Complete

All serial features: timeouts, flow control, buffers

PySerial handles platform differences so you can focus on your application.

Quick Start

Install PySerial

pip install pyserial

conda install -c conda-forge pyserial

# Ubuntu/Debian
sudo apt install python3-serial

# macOS with Homebrew
brew install python3 && pip3 install pyserial

Find Your Device

import serial.tools.list_ports

ports = serial.tools.list_ports.comports()
for port in ports:
    print(f"{port.device}: {port.description}")

Basic Communication

import serial

# Open connection
ser = serial.Serial('/dev/ttyUSB0', 9600, timeout=1)

# Send data
ser.write(b'Hello Serial World!\n')

# Read response
response = ser.readline()
print(response.decode('utf-8').strip())

# Close connection
ser.close()

Common Use Cases

Arduino Projects

Control microcontrollers and read sensor data

Industrial Automation

Connect to PLCs, modems, and instruments

GPS & Navigation

Parse NMEA data from GPS modules

IoT Devices

Bridge serial devices to the internet

Platform Support

Windows

COM ports (COM1, COM3, etc.)
USB-serial adapters with drivers
Built-in serial ports

Linux

/dev/ttyUSB* for USB-serial adapters
/dev/ttyACM* for Arduino and modems
/dev/ttyS* for built-in serial ports

macOS

/dev/cu.* for output connections
/dev/tty.* for input connections
USB-serial adapters supported

Real-World Example

Temperature monitoring with Arduino:

import serial
import json
import time

# Connect to Arduino
arduino = serial.Serial('/dev/ttyACM0', 9600, timeout=2)
time.sleep(2)  # Wait for Arduino reset

try:
    while True:
        # Read JSON data from Arduino
        line = arduino.readline().decode('utf-8').strip()
        
        if line.startswith('{'):
            data = json.loads(line)
            temp = data['temperature']
            humidity = data['humidity']
            
            print(f"Temperature: {temp}°C, Humidity: {humidity}%")
            
            # Alert on high temperature
            if temp > 30:
                print("⚠️  High temperature alert!")
                
except KeyboardInterrupt:
    print("Monitoring stopped")
finally:
    arduino.close()

Error Handling

Always include proper error handling:

import serial

try:
    ser = serial.Serial('/dev/ttyUSB0', 9600, timeout=1)
    # Your serial operations here
    
except serial.SerialException as e:
    print(f"Serial port error: {e}")
except PermissionError:
    print("Permission denied - check user permissions")
except FileNotFoundError:
    print("Port not found - verify device connection")
finally:
    if 'ser' in locals() and ser.is_open:
        ser.close()

Next Steps

Getting Started

Detailed setup and first connection

Arduino Integration

Connect Python to Arduino projects

Reading Data

Master all reading methods and techniques

Examples

Real-world projects and code samples

Ready to Connect: PySerial makes serial communication simple and reliable across any platform. Start building your serial applications today!

How is this guide?