ephemeral-port-reserve

What it is and what it does

ephemeral-port-reserve solves the problem of allocating unused network ports when the standard "port 0 trick" fails or is unreliable. Some applications like mysqld or Docker interpret port 0 specially rather than letting the kernel choose a free port, and Docker's port allocation can race under parallelism. This package provides a race-free alternative by binding to an ephemeral port, forcing it into TIME_WAIT state, and unbinding it—reserving that port so the kernel won't reuse it for a grace period (typically 60 seconds on Linux), while still allowing subprocesses to bind to it explicitly if they use SO_REUSEADDR.

It's typically used in test suites, containerized deployments, and parallel service startup scenarios where you need to guarantee port availability without hard-coding. The package has no runtime dependencies, supports Python 2.7 and 3.5 through 3.8, and is maintained as a small, focused utility.

Use it for:

• Running multiple Docker containers in parallel without port conflicts by reserving ports before container startup.
• Allocating ports for parallel test services in CI/CD pipelines where port 0 is unreliable.
• Starting multiple instances of mysqld or similar daemons that don't honor port 0 as a kernel-allocation signal.
• Ensuring port availability in containerized test environments where standard ephemeral allocation races.
• Scripting port reservation for subprocess startup when you need to pass the port number to child processes.

Worth the install?

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

Reserves an ephemeral port reliably and race-free by binding, forcing it into TIME_WAIT state, and unbinding, so subprocesses can bind to it explicitly without conflict.

Yes, if you need race-free ephemeral port allocation in parallel or containerized scenarios where port 0 doesn't work. The package is lightweight, has no dependencies, carries a permissive license, and is actively maintained. Install it only if you hit the specific problem it solves; it's not a general-purpose utility.

Install

ephemeral-port-reserve on PyPI

pip install ephemeral-port-reserve

uv add ephemeral-port-reserve

poetry add ephemeral-port-reserve

Installing ephemeral-port-reserve

Before you install

No runtime dependencies and low install friction. Repository is active with recent commits (last commit 2026-04-02) and has been maintained since 2016, though the latest release was 2021-02-11.

License in practice

MIT license is permissive and imposes no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart

pip install ephemeral-port-reserve

from ephemeral_port_reserve import reserve
port = reserve()
print(port)  # Returns an available port number

Requires a Unix-like system with socket support; behavior and grace period (default 60 seconds on Linux) are OS-dependent.

Verify before relying

• Whether the package works reliably on Windows or other non-Linux systems.
• Current test coverage and whether the race-free guarantee holds under high concurrency.
• Whether the 60-second TIME_WAIT grace period is configurable or system-dependent only.

Package facts

Evidence: ephemeral_port_reserve-1.1.4-py2.py3-none-any.whl

Tags

More Networking packages