Install & Compatibility
Where this runs
tested against v3.5.0.20260712 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Serial
✓ from serial_stubs import Serial
✗ from serial_stubs import Serial
This quickstart demonstrates basic serial communication using `pyserial`. With `types-pyserial` installed, a type checker will provide accurate type hints and catch errors for functions, classes, and methods imported from the `serial` module, such as `Serial`, `write`, `readline`, and `is_open`. The `SERIAL_PORT` environment variable is used for demonstration, but you should replace it with your device's actual serial port.
import os
from serial import Serial
# Replace with your actual serial port name (e.g., 'COM1' on Windows, '/dev/ttyUSB0' on Linux)
SERIAL_PORT = os.environ.get('SERIAL_PORT', '/dev/ttyUSB0')
BAUDRATE = 9600
def communicate_with_serial(port: str, baud: int) -> None:
ser: Serial | None = None
try:
# The `Serial` class is correctly typed by types-pyserial
ser = Serial(port, baud)
print(f"Opened serial port {port} at {baud} baud.")
# Example: Write data
message_to_send = b"Hello, device!\n"
ser.write(message_to_send)
print(f"Sent: {message_to_send.decode().strip()}")
# Example: Read data (with a timeout)
ser.timeout = 1 # seconds
received_data = ser.readline()
if received_data:
print(f"Received: {received_data.decode().strip()}")
else:
print("No data received within timeout.")
except Exception as e:
print(f"Error during serial communication: {e}")
finally:
if ser and ser.is_open:
ser.close()
print(f"Closed serial port {port}.")
if __name__ == "__main__":
communicate_with_serial(SERIAL_PORT, BAUDRATE)
Debug
Known issues
gotchaThe PyPI package name is `types-pyserial`, but the runtime library is imported as `serial` (i.e., `import serial`). Confusing these can lead to `ModuleNotFoundError` or incorrect type checking behavior if an unrelated `serial` package is installed.fixAlways use `pip install types-pyserial` for the stubs and `from serial import ...` in your Python code. Ensure `pyserial` is also installed via `pip install pyserial`.
affects: All versions
breakingType stub versions are primarily tied to the major.minor version of the runtime package they describe. For example, `types-pyserial==3.5.*` targets `pyserial==3.5.*`. If `pyserial` updates its API (especially in a major or minor release), the corresponding `types-pyserial` stubs will also update, potentially causing new type-checking errors if your application's code relies on older APIs.fixPin `types-pyserial` to the specific major.minor version of `pyserial` you are using (e.g., `pyserial~=3.5, types-pyserial~=3.5`). Regularly review and update both packages together to stay compatible and benefit from the latest type definitions.
affects: All versions
gotcha`types-pyserial` is a stub-only package and provides no runtime functionality. It is solely used by static type checkers. If `pyserial` (the actual runtime library) is not installed, your code will fail at runtime with an `ImportError`, even if `types-pyserial` is present.fixAlways install both the runtime library and its corresponding stubs: `pip install pyserial types-pyserial`.
affects: All versions
gotchaTypeshed stub packages are automatically released, sometimes as frequently as once a day. While this ensures up-to-date annotations, it means `types-pyserial` can update more frequently than your runtime `pyserial` package or your type checker, potentially introducing new type errors due to changes in stub definitions or reliance on newer typing features.fixPin `types-pyserial` to a specific version or a tighter range (e.g., `types-pyserial==3.5.0.20260408`) and update it deliberately, especially when upgrading your type checker or the `pyserial` runtime library. Always test type checking in your CI/CD pipeline.
affects: All versions
gotchaTypeshed (and thus `types-pyserial`) generally supports a range of recent Python versions. Ensure your Python environment is within the supported range (e.g., 3.10 to 3.14 for current typeshed) to guarantee correct stub interpretation by your type checker.fixUpgrade your Python environment to a version supported by the latest typeshed stubs (currently Python 3.10+).
affects: Python versions older than 3.10
Upgrade
Version history
3.5.0.20260712latest on PyPI · released Jul 12, 2026
Audit
Dependencies
pyserialrequiredThese are typing stubs for the 'pyserial' runtime library. The 'pyserial' package must be installed separately for your application to function at runtime.