Install & Compatibility
Where this runs
tested against v2.8.0 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.391s · 32.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.1s · import 0.339s · 33MB
31MB installed
● package 31MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Dut
✓ from pytest_embedded import Dut
pytest-embedded-serial extends the Dut fixture provided by pytest-embedded. You typically import Dut from pytest_embedded and the serial functionalities are automatically available if pytest-embedded-serial is installed and enabled.
SerialDut
✓ from pytest_embedded_serial.dut import SerialDut
✗ from pytest_embedded.dut import SerialDut
While SerialDut is available for direct import, the recommended way to interact with serial capabilities in tests is through the `dut: Dut` fixture, which pytest-embedded-serial enhances.
This quickstart demonstrates how to write a basic pytest-embedded test that utilizes serial communication. It uses the `dut` fixture, which is automatically enhanced by `pytest-embedded-serial` when installed. The example shows writing commands to the device under test (DUT) and expecting specific responses using `dut.write()` and `dut.expect_exact()`. The `serial` service is often automatically enabled when the package is installed, or can be explicitly enabled via `pytest --embedded-services serial` CLI option.
import pytest
from pytest_embedded import Dut
import os
# Assuming a device is connected via serial port
# You can specify the port via CLI: pytest --port /dev/ttyUSB0 (or COMx on Windows)
# Or set it via an environment variable or pytest.ini
def test_serial_communication(dut: Dut):
# Ensure the 'serial' service is enabled, e.g., via CLI: pytest --embedded-services serial
# or by default if pytest-embedded-serial is installed.
# Example: Write data to the serial port and expect a response
# Replace with actual device interaction logic
dut.write('hello device')
dut.expect_exact('echo: hello device', timeout=5)
print("Device responded to 'hello device'.")
# Accessing underlying serial object (for advanced use cases)
# The dut.serial object is an instance of Serial from pytest_embedded_serial.serial
# It's generally preferred to use dut.write and dut.expect for standard interactions.
# serial_port = dut.serial
# print(f"Connected to serial port: {serial_port.port} at baudrate: {serial_port.baud}")
dut.write('get status')
dut.expect(r'Status: (\w+)', timeout=5)
status = dut.match.group(1).decode('utf-8')
print(f"Device status: {status}")
assert status == 'OK'
Debug
Known issues
breakingPython 3.7, 3.8, and 3.9 are no longer supported by the pytest-embedded ecosystem, including pytest-embedded-serial. Projects using these older Python versions must upgrade to Python 3.10 or newer.fixUpgrade your Python environment to version 3.10 or later. Update your `pytest-embedded` and `pytest-embedded-serial` installations: `pip install -U 'pytest-embedded~=2.0' 'pytest-embedded-serial~=2.0'`.
affects: pytest-embedded>=2.0.0
gotchaFile descriptor leaks can occur when using `pytest-embedded-serial` in conjunction with `pytest-lazy-fixture` in older versions of `pytest-embedded`, leading to resource exhaustion.fixEnsure you are using the latest stable version of `pytest-embedded` and `pytest-embedded-serial` to benefit from the fix. `pip install -U pytest-embedded pytest-embedded-serial`.
affects: < pytest-embedded 2.1.2 (fixed in commit #234 around Nov 2023)
gotchaThe `pytest-embedded` framework (and by extension `pytest-embedded-serial`) uses internal threading. When conducting performance tests, using Python's `threading` module might lead to performance degradation due to the Global Interpreter Lock (GIL).fixFor performance-critical tests or scenarios requiring true parallelism, consider using Python's `multiprocessing` module instead of `threading`. The APIs are often similar.
affects: All versions
Errors
Common errors & fixes
serial.serialutil.SerialException: [Errno 13] could not open port /dev/ttyUSB0: [Errno 13] Permission denied: '/dev/ttyUSB0'
The current user does not have read/write permissions for the specified serial port. This is a common issue on Linux-based systems where serial ports are owned by the 'dialout' or 'uucp' group.
fixAdd your user to the appropriate group (e.g., 'dialout') and then log out and back in for the changes to take effect. On Linux: `sudo usermod -a -G dialout $USER`. Ensure the port path is correct (`/dev/ttyUSB0` or `COMx` on Windows).
serial.serialutil.SerialException: No such file or directory: '/dev/ttyS99'
The specified serial port does not exist or is not connected. This could be due to an incorrect port name, a disconnected device, or a missing driver.
fixVerify the correct serial port name for your operating system (e.g., check device manager on Windows, `ls /dev/tty*` on Linux). Ensure the device is properly connected and its drivers are installed.
pexpect.exceptions.TIMEOUT: Timeout exceeded in command 'dut.expect('...')'
The expected pattern was not received from the serial device within the allotted timeout period. This could be due to the device not responding, an incorrect expected pattern, or a too-short timeout.
fixIncrease the `timeout` parameter in `dut.expect()` or `dut.expect_exact()` calls. Verify the expected pattern matches the device's actual output, considering line endings or other formatting. Debug the device's firmware to ensure it sends the expected response.
Upgrade
Version history
2.8.0latest on PyPI · released May 15, 2026
Audit
Dependencies
pytest-embeddedrequiredThis plugin extends the core pytest-embedded framework.
pyserialrequiredUnderlying library for serial communication. While not a direct pip dependency of pytest-embedded-serial (it is usually handled by pytest-embedded's installation or implicitly via its internal components), it's essential for serial functionality.