Installing PySerial
Complete PySerial installation guide for Windows, Linux, and macOS. pip, conda, apt, and troubleshooting tips included.
Install PySerial on any platform with these step-by-step guides.
Quick Install
Just want to get started? Run pip install pyserial and you're ready to go on most systems.
pip install pyserialThat's it for most systems. If you need platform-specific help, read on.
Installation Methods
Install:
pip install pyserialUpgrade:
pip install --upgrade pyserialSpecific version:
pip install pyserial==3.5Check installation:
pip show pyserialInstall:
conda install -c conda-forge pyserialCreate environment:
conda create -n serial-env python=3.9 pyserial
conda activate serial-envUbuntu/Debian:
sudo apt update
sudo apt install python3-serialCentOS/RHEL/Fedora:
# Fedora
sudo dnf install python3-pyserial
# CentOS/RHEL
sudo yum install python3-pyserialArch Linux:
sudo pacman -S python-pyserialmacOS (Homebrew):
brew install python3
pip3 install pyserialPlatform-Specific Setup
Windows
Install Python
- Download from python.org
- Important: Check "Add Python to PATH" during installation
- Verify:
python --version
Install PySerial
pip install pyserialFor PyCharm/Visual Studio Code:
- Open terminal in your IDE
- Run
pip install pyserial - Restart your IDE
Common Windows Issues
Permission Error:
# Run as administrator or use --user
pip install --user pyserialPath Issues:
# Use full path if needed
C:\Python39\Scripts\pip install pyserialLinux
Standard Install
# Most distributions
pip install pyserial
# Or system package
sudo apt install python3-serial # Ubuntu/DebianFix Permissions
Serial ports need special permissions on Linux:
# Add user to dialout group
sudo usermod -a -G dialout $USER
# Apply immediately (or logout/login)
newgrp dialout
# Verify
groupsCheck Port Permissions
# List serial ports
ls -l /dev/tty{USB,ACM}*
# Should show: crw-rw---- root dialout
# If not, fix with:
sudo chmod 666 /dev/ttyUSB0 # TemporarymacOS
Install Python
# Using Homebrew (recommended)
brew install python3
# Verify
python3 --versionInstall PySerial
pip3 install pyserialSecurity Settings
macOS Catalina+ may require permission for Terminal/IDE to access devices:
- System Preferences → Security & Privacy
- Privacy tab → Full Disk Access
- Add Terminal or your IDE
Virtual Environments
Best Practice: Always use virtual environments to avoid conflicts between projects.
Using venv (Built-in)
# Create environment
python -m venv serial-project
# Activate
source serial-project/bin/activate # Linux/macOS
serial-project\Scripts\activate # Windows
# Install PySerial
pip install pyserial
# Deactivate when done
deactivateUsing conda
# Create environment
conda create -n serial-env python=3.9
# Activate
conda activate serial-env
# Install
conda install -c conda-forge pyserial
# Deactivate
conda deactivateVerify Installation
Test that PySerial is working correctly:
# test_pyserial.py
import serial
import serial.tools.list_ports
print(f"PySerial version: {serial.__version__}")
# List available ports
print("Available serial ports:")
ports = serial.tools.list_ports.comports()
if not ports:
print(" No serial ports found")
else:
for port in ports:
print(f" {port.device}: {port.description}")
# Test basic functionality
try:
# This will fail if no port exists, but tests import
ser = serial.Serial()
print("✓ PySerial imported successfully")
ser.close()
except Exception as e:
print(f"⚠️ Warning: {e}")Run the test:
python test_pyserial.pyExpected output:
PySerial version: 3.5
Available serial ports:
/dev/ttyUSB0: USB-Serial Controller
✓ PySerial imported successfullyTroubleshooting
ModuleNotFoundError
Error: ModuleNotFoundError: No module named 'serial'
Wrong Package
Installed 'serial' instead of 'pyserial'
Virtual Environment
PySerial installed in different environment
Python Version
Multiple Python versions installed
Solutions:
# Remove wrong package
pip uninstall serial
# Install correct package
pip install pyserial
# Import correctly (not 'import pyserial')
import serialPermission Denied (Linux)
Error: PermissionError: [Errno 13] Permission denied: '/dev/ttyUSB0'
Fix:
# Add user to dialout group
sudo usermod -a -G dialout $USER
# Log out and back in, or:
newgrp dialoutPort Not Found
Error: SerialException: could not open port
Debug steps:
# Linux: List ports
ls /dev/tty{USB,ACM,S}*
# Windows: Check Device Manager
# macOS: List ports
ls /dev/cu.* /dev/tty.*# Python: Auto-detect ports
import serial.tools.list_ports
for port in serial.tools.list_ports.comports():
print(f"Found: {port.device} - {port.description}")Multiple Python Versions
If you have multiple Python installations:
# Check which Python
which python
which python3
# Install to specific version
python3.9 -m pip install pyserial
# Or use py launcher (Windows)
py -3.9 -m pip install pyserialIDE Configuration
PyCharm
- File → Settings → Project → Python Interpreter
- Click gear icon → Add...
- Create new virtual environment or use existing
- Install pyserial via package manager
VS Code
- Install Python extension
- Select interpreter:
Ctrl+Shift+P→ "Python: Select Interpreter" - Open terminal and run:
pip install pyserial
Jupyter Notebook
# Install in Jupyter's environment
pip install pyserial
# Or in notebook cell
!pip install pyserialDocker Support
Dockerfile:
FROM python:3.9-slim
# Install PySerial
RUN pip install pyserial
# Add user to dialout group (for device access)
RUN groupadd dialout && useradd -G dialout pyserial-user
COPY . /app
WORKDIR /app
USER pyserial-userRun with device access:
# Map serial device to container
docker run --device=/dev/ttyUSB0 myapp
# Or grant access to all serial devices
docker run --privileged myappDevelopment Installation
Install from source for latest features:
# Clone repository
git clone https://github.com/pyserial/pyserial.git
cd pyserial
# Install in development mode
pip install -e .
# Or install from GitHub directly
pip install git+https://github.com/pyserial/pyserial.gitNext Steps
After successful installation:
Getting Started
Make your first serial connection
Arduino Integration
Connect to Arduino projects
Common Errors
Fix typical installation and runtime issues
Examples
Working code examples
Installation Complete! PySerial is ready for cross-platform serial communication.
Quick Test
Test your installation with this simple script:
import serial.tools.list_ports
# List all available ports
ports = list(serial.tools.list_ports.comports())
print(f"Found {len(ports)} serial port(s):")
for port in ports:
print(f" {port.device}: {port.description}")
print("\nPySerial is ready to use!")How is this guide?
