portend

What it is and what it does

Portend is a lightweight TCP port monitoring library that lets you wait for a port to become occupied (bound by a listener) or free (unbound), with configurable timeouts. It's commonly used in test setup, service orchestration, and deployment scripts where you need to verify that a service has started or that a port is available before binding to it.

The package provides a simple API with two main functions—`occupied()` and `free()`—plus utilities like `find_available_local_port()` to discover an unused port and a lower-level `Checker` class for more direct control. It can also be invoked as a command-line tool via `python -m portend`, making it useful in shell scripts and CI/CD pipelines. The only runtime dependency is tempora, keeping the installation footprint minimal.

Use it for:

• Wait for a service to start up in integration tests before running test suites that depend on it
• Find an available local port to bind a test server without port conflicts
• Verify port availability in deployment or orchestration scripts before starting a service
• Monitor a remote port (e.g., a database or API server) to detect when it becomes available after a restart
• Implement health checks in CI/CD pipelines that need to confirm a service is listening before proceeding

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Portend monitors TCP ports to check whether they are bound (occupied) or free, and can find available local ports for binding.

Yes. Portend solves a common, specific problem (TCP port state checking) with a minimal dependency footprint, active maintenance, no known vulnerabilities, and a permissive license. It's well-suited for test automation, service orchestration, and deployment workflows. Install it if you need to wait for ports or discover available ones in Python or shell scripts.

Install

portend on PyPI

pip install portend

uv add portend

poetry add portend

Installing portend

Before you install

Low install friction: pure Python wheel with a single runtime dependency (tempora). Actively maintained with recent commits; last release was 2025-05-29 and the repository shows ongoing activity.

License in practice

MIT license is permissive and places no significant restrictions on use, modification, or distribution in commercial or private projects.

Quickstart

pip install portend

import portend

# Wait for a port to be occupied (with 3 second timeout)
portend.occupied('www.google.com', 80, timeout=3)

# Or find an available local port
port = portend.find_available_local_port()
print(port, "is available for binding")

Requires Python 3.9 or later.

Verify before relying

• Whether the package handles IPv6 addresses reliably (the description mentions '::1' but does not detail IPv6 support scope)
• Performance characteristics when monitoring many ports concurrently or in rapid succession

Package facts

Evidence: portend-3.2.1-py3-none-any.whl

Tags

More Monitoring packages