Install & Compatibility
Where this runs
tested against v0.10.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.910 runs
installs and imports cleanly · install 0.0s · import 0.262s · 21.4MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.9s · import 0.244s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
http
✓ from pytest_localserver import http
✗ import pytest_localserver.http
While 'import' works, 'from ... import http' is common for direct access to its classes like Server.
smtp
✓ from pytest_localserver import smtp
✗ import pytest_localserver.smtp
Similar to 'http', 'from ... import smtp' is preferred for direct access to SMTP server components.
Server
✓ from pytest_localserver.http import Server
✗ from pytest_localserver.http import HTTPServer
The primary HTTP server class is named `Server` within the `http` module, not `HTTPServer`.
This quickstart demonstrates how to set up a local HTTP server with a simple WSGI application using pytest-localserver. It defines a pytest fixture that starts the server before tests and stops it afterwards. The example then shows a test function that uses `requests` to make a call to the local server's URL and asserts the response.
import pytest
from pytest_localserver.http import WSGIHandler, Server
# Define a simple WSGI application
def my_app(environ, start_response):
status = '200 OK'
headers = [('Content-type', 'text/plain; charset=utf-8')]
start_response(status, headers)
return [b"Hello, World!"]
# Create a fixture for the local HTTP server
@pytest.fixture
def http_server():
# Instantiate the WSGI handler with your app
handler = WSGIHandler(my_app)
# Start the server
server = Server(handler)
server.start()
yield server
# Stop the server after the test
server.stop()
# Example test using the http_server fixture
def test_my_app_endpoint(http_server):
import requests
# Access the server URL provided by the fixture
response = requests.get(http_server.url)
assert response.status_code == 200
assert response.text == "Hello, World!"
Debug
Known issues
breakingPython 3.6 support has been dropped. Users on Python 3.6 must remain on version 0.9.x or earlier.fixUpgrade to Python 3.7 or newer, or pin `pytest-localserver<0.10.0`.
affects: 0.10.0 and later
breakingThe minimum required pytest version was raised to `pytest>=4.6`. Users working with older pytest versions (e.g., `pytest>=4,<4.6`) must stay on `pytest-localserver<0.9.0.post0`.fixUpgrade pytest to version 4.6 or newer, or pin `pytest-localserver<0.9.0.post0`.
affects: 0.9.0.post0 and later
breakingSMTP server support is no longer installed by default. To use the SMTP server, you must install `pytest-localserver` with the `[smtp]` extra.fixInstall using `pip install 'pytest-localserver[smtp]'`.
affects: 0.7.0 and later
gotchaThe SMTP server internally uses `aiosmtpd`, which had breaking changes (e.g., removal of `_stop` method in 1.4.3+). While `pytest-localserver` attempts to handle this, ensure compatibility if explicitly interacting with `aiosmtpd` versions.fixEnsure `pytest-localserver` is up-to-date (0.7.1+) if experiencing issues with newer `aiosmtpd` versions or if you need to manually interact with `aiosmtpd`'s API.
affects: 0.6.0 onwards (due to `aiosmtpd` integration), specifically `aiosmtpd` 1.4.3+ required `pytest-localserver>=0.7.1` for a fix.
Errors
Common errors & fixes
TypeError: 'int' object is not callable
The user is attempting to call `httpserver.port` or `httpserver.host` as methods (e.g., `httpserver.port()`) instead of accessing them as attributes.
fixAccess `host` and `port` directly as attributes, for example: `url = f"http://{httpserver.host}:{httpserver.port}"` ModuleNotFoundError: No module named 'pytest_localserver.http.TestServer'
The user is trying to import `TestServer` directly from a deeply nested or incorrect module path, rather than importing the `http` module from `pytest_localserver`.
fixImport the `http` module and use `http.HTTPTestServer`, or simply use the `httpserver` fixture directly provided by the plugin.
ImportError: cannot import name 'httptestserver' from 'pytest_localserver'
The user is attempting to import the `httptestserver` fixture or the `HTTPTestServer` class directly from the top-level `pytest_localserver` package, but these objects are defined within submodules like `pytest_localserver.http`.
fixUse the provided `httpserver` fixture in your test function signature, or if you need to access the class directly, import it via `from pytest_localserver import http` and then use `http.HTTPTestServer`.
AttributeError: 'NoneType' object has no attribute 'port'
This error typically occurs when the `smtpserver` or `httpserver` fixture fails to initialize or is not properly yielded, resulting in a `None` object when its attributes like `port` are accessed.
fixEnsure the test setup correctly uses the server fixture (e.g., `smtpserver` or `httpserver`) and that no exceptions occur during the server's initialization within the fixture, which might indicate a port conflict or configuration issue.
Upgrade
Version history
0.10.0latest on PyPI · released Nov 24, 2025
Audit
Dependencies
pytestrequiredCore dependency for the pytest plugin framework.
WerkzeugrequiredUsed for the HTTP server implementation.
trustmerequiredUsed for generating certificates for HTTPS servers.
aiosmtpdoptionalProvides the asynchronous SMTP server implementation. Only required if using the SMTP server via the '[smtp]' extra.