---
id: portend
version: "3.2.1"
license: MIT
license_treatment: permissive
maintenance: active
---

# portend — TCP port monitoring and discovery

License: permissive · Maintenance: active · Downloads: 890.0K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 890.0K/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

tcp port monitoring, check if port is open, wait for port to be free, find available port, port binding checker, port availability detection, tcp port state checker, port-monitoring, tcp-utilities, test-infrastructure

[View on SkillFed](https://skillfed.io/packages/portend) · [View on PyPI](https://pypi.org/project/portend/)