Introduction
Serialx is a no-compromise serial communication library for Python targeting common platforms such as Linux (POSIX), macOS, and Windows. It provides both synchronous and native asynchronous APIs for all platforms.
For more information, visit serialx's documentation: https://puddly.github.io/serialx/
Installation
pip install serialx
For drop-in import compatibility (serial, serial_asyncio, serial_asyncio_fast) in
environments where existing code cannot be migrated:
pip install serialx-compat
Usage
Serialx features a familiar synchronous API:
import serialx
with serialx.serial_for_url("/dev/serial/by-id/port", baudrate=115200) as serial:
data = serial.readexactly(5)
serial.write(b"test")
serial.set_modem_pins(rts=True, dtr=True)
pins = serial.get_modem_pins()
assert pins.rts is serialx.PinState.HIGH
assert pins.dtr is serialx.PinState.HIGH
An async equivalent of the synchronous API:
import asyncio
import serialx
async def main():
async with serialx.async_serial_for_url(
"/dev/serial/by-id/port", baudrate=115200,
) as serial:
data = await serial.readexactly(5)
await serial.write(b"test")
await serial.set_modem_pins(rts=True, dtr=True)
pins = await serial.get_modem_pins()
assert pins.rts is serialx.PinState.HIGH
A (StreamReader, StreamWriter) pair is also available for code already wired up to
the asyncio streams API:
import asyncio
import serialx
async def main():
reader, writer = await serialx.open_serial_connection(
"/dev/serial/by-id/port", baudrate=115200,
)
try:
data = await reader.readexactly(5)
writer.write(b"test")
await writer.drain()
finally:
writer.close()
await writer.wait_closed()
And a low-level asynchronous serial transport for protocol-style consumers:
import asyncio
import serialx
async def main():
loop = asyncio.get_running_loop()
protocol = YourProtocol()
transport, protocol = await serialx.create_serial_connection(
loop,
lambda: protocol,
url="/dev/serial/by-id/port",
baudrate=115200,
)
await transport.set_modem_pins(rts=True, dtr=True)
ESPHome serial proxy
Serialx can communicate with serial devices exposed by ESPHome.
It can either create the API instance directly, for simplicity:
from serialx import open_serial_connection
reader, writer = await open_serial_connection(
url="esphome://192.168.1.42:6053/?port_name=Zigbee&key=...",
baudrate=115200,
)
Or reuse an existing API instance, for efficiency:
from aioesphomeapi import APIClient
from serialx import open_serial_connection
from serialx.platforms.serial_esphome import ESPHomeSerialTransport
# An external API instance
api = APIClient(address="192.168.1.42", port=6053, key="...", password=None)
await api.connect(login=True)
reader, writer = await open_serial_connection(
url=None,
transport_cls=ESPHomeSerialTransport,
api=api,
port_name="Zigbee",
baudrate=115200,
)
Development
All development dependencies are listed in the dev dependency group in
pyproject.toml. To install them into a .venv (activate it afterwards, or prefix
commands with uv run), use:
uv sync
On macOS and Windows, a Rust toolchain is required to build the native serial port enumeration extension. Install Rust via rustup.
Set up pre-commit hooks with prek install. Your code will then be type checked
and auto-formatted when you run git commit. You can do this on-demand with
prek run.
Serialx relies on automated testing. CI runs tests using both socat virtual PTYs
(Linux/macOS) and socket-based serial pairs. To also test with physical adapter pairs,
pass CLI flags to pytest:
pytest --adapter-pair=/dev/serial/by-id/left1,/dev/serial/by-id/right1 \
--adapter-pair=/dev/serial/by-id/left2,/dev/serial/by-id/right2
Each test runs once, on any one of the pairs. More pairs let more pytest-xdist
workers run adapter tests at once.
By default, tests run in parallel. You can disable this by passing -n 0 to pytest.
1 maintainer
Metadata
1 maintainer
Release files for serialx 1.12.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| serialx-1.12.0.tar.gz | 384.1 kB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| serialx-1.12.0-py3-none-any.whl | Python 3 | none | any | Details |
| serialx-1.12.0-cp310-abi3-win_arm64.whl | CPython 3.10 | abi3 | Windows ARM64 | Details |
| serialx-1.12.0-cp310-abi3-win_amd64.whl | CPython 3.10 | abi3 | Windows x86-64 | Details |
| serialx-1.12.0-cp310-abi3-win32.whl | CPython 3.10 | abi3 | Windows x86-32 | Details |
| serialx-1.12.0-cp310-abi3-macosx_11_0_arm64.whl | CPython 3.10 | abi3 | macOS 11.0+ ARM64 | Details |
| serialx-1.12.0-cp310-abi3-macosx_10_12_x86_64.whl | CPython 3.10 | abi3 | macOS 10.12+ x86-64 | Details |
Total release size: 1.7 MB
Release files / serialx-1.12.0.tar.gz
| Download URL | serialx-1.12.0.tar.gz |
|---|---|
| Size | 384.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e19e45ba198e919b86952f428376207c8dae39b741546e02e8e5657981cc3b1d
|
|
BLAKE2b-256 checksum How to use checksums |
c768efe61ac6dd5fe536eba0a3a23e92d09caa9e78cc59f97bdeb594a0098ada
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logRelease files / serialx-1.12.0-py3-none-any.whl
| Download URL | serialx-1.12.0-py3-none-any.whl |
|---|---|
| Size | 85.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8db3e5ad283142114150b9610979a1895881f03799cb9a42b792b2b6619d5d03
|
|
BLAKE2b-256 checksum How to use checksums |
d8590b348a22d64879cbb686da339b5be20bab560722dd70f9c755cab7e2fc42
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logRelease files / serialx-1.12.0-cp310-abi3-win_arm64.whl
| Download URL | serialx-1.12.0-cp310-abi3-win_arm64.whl |
|---|---|
| Size | 207.2 kB |
| Tags | CPython 3.10 Windows ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
db0764be45f5492e19cfb7da36c0740d817431a44a610dcf405be94a166c757d
|
|
BLAKE2b-256 checksum How to use checksums |
02e08a6236998551f1204f1f16cffb57b0a324af433a41f7d60d78aae48de707
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logRelease files / serialx-1.12.0-cp310-abi3-win_amd64.whl
| Download URL | serialx-1.12.0-cp310-abi3-win_amd64.whl |
|---|---|
| Size | 210.6 kB |
| Tags | CPython 3.10 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
9fc4435fc7161066af340821a010a8e6c061aa919ae927c3fd88a2b4b8fbc735
|
|
BLAKE2b-256 checksum How to use checksums |
726ca957a22b563cd5c07a7d7ada5c3aa65a48418be7a917fc680f63ab26fcdc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logRelease files / serialx-1.12.0-cp310-abi3-win32.whl
| Download URL | serialx-1.12.0-cp310-abi3-win32.whl |
|---|---|
| Size | 203.2 kB |
| Tags | CPython 3.10 Windows x86-32 abi3 |
|
SHA-256 checksum How to use checksums |
0b19198ce6354dfdf6bf345dbd39947738dc7bacbdd061016682ce5a03405d01
|
|
BLAKE2b-256 checksum How to use checksums |
99a921ca6d2fe84b0ec74b20a5c11dcc696af120ff362e2fe6d5a42364a06b8e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logRelease files / serialx-1.12.0-cp310-abi3-macosx_11_0_arm64.whl
| Download URL | serialx-1.12.0-cp310-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 300.2 kB |
| Tags | CPython 3.10 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
c906968be49dba169226a90fb0ba804f36e069b2204f1f353bf63b8523c5e582
|
|
BLAKE2b-256 checksum How to use checksums |
7c2b3022d48b7830e69c4d9013854869346edfb81de28fe9d6bd3750c4cb1b42
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logRelease files / serialx-1.12.0-cp310-abi3-macosx_10_12_x86_64.whl
| Download URL | serialx-1.12.0-cp310-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 304.2 kB |
| Tags | CPython 3.10 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
f37a1a2b1401f681a17f6b6e34647f624b1e808b758e86402bb8e75631987b6c
|
|
BLAKE2b-256 checksum How to use checksums |
52f99619c727357b2d0c3fa19ca17e152318db4448b75d9fd1d10c23b112639b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency log
