---
id: ephemeral-port-reserve
version: "1.1.4"
license: MIT
license_treatment: permissive
maintenance: active
---

# ephemeral-port-reserve — Bind to an ephemeral port, force it into the TIME_WAIT state, and unbind it.

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

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

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

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

## Tags

ephemeral port allocation, reserve unused port, port 0 trick alternative, race-free port binding, docker port conflict, parallel service ports, port reservation utility, port-allocation, testing-utilities, docker-support

[View on SkillFed](https://skillfed.io/packages/ephemeral-port-reserve) · [View on PyPI](https://pypi.org/project/ephemeral-port-reserve/)