port-for

What it is and what it does

port-for is a command-line utility and Python library that selects and persists unused TCP localhost ports. Unlike socket.bind((host, 0)), which returns temporary OS-assigned ports, port-for finds ports that are less likely to be claimed by the operating system or other services, making it suitable for durable service configurations across restarts.

The library applies several heuristics: it verifies ports are unused by attempting to connect and bind, excludes IANA-assigned and well-known ports, avoids ephemeral port ranges (which the OS may reclaim), and prefers ports from larger ranges away from well-known services. It can store port-to-name associations in a configuration file, allowing subsequent calls to return the same port for a given service name.

Use it for:

• Allocate persistent ports for multiple services in a local development stack without manual port assignment.
• Ensure service restarts use the same port by querying the stored association via the command-line tool.
• Programmatically select safe ports in test suites or deployment scripts that need to avoid OS-assigned ephemeral ranges.
• Configure multi-tenant or multi-site setups on a single server by naming ports with conventions (e.g., 'example.com/apache').
• Build port management into installation scripts that need to find available ports without manual intervention.

Worth the install?

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

port-for finds and remembers unused TCP localhost ports, useful for persistent port allocation across service restarts and multi-component software stacks.

Yes. port-for solves a real problem—persistent, safe port allocation—with no dependencies, active maintenance, MIT licensing, and no known vulnerabilities. It is well-suited for development stacks, testing frameworks, and deployment automation. The only caveat is that the command-line tool requires sudo to create new associations, which may limit its use in restricted environments.

Install

port-for on PyPI

pip install port-for

uv add port-for

poetry add port-for

Installing port-for

Before you install

Low install friction with no runtime dependencies. Actively maintained with recent commits and support for current Python versions (3.10 through 3.14).

License in practice

MIT license permits unrestricted use, modification, and distribution with minimal restrictions—suitable for most commercial and open-source projects.

Quickstart

pip install port-for

import port_for
port = port_for.select_random()
print(port)  # e.g., 37774

# Or use the command-line tool:
# $ port-for myservice
# 37987

The command-line tool requires read/write access to /etc/port-for.conf; regular users can read but sudo is needed to create new port associations.

Verify before relying

• Whether the IANA unassigned ports list is kept current and how often it is updated.
• Behavior and reliability of port selection across different operating systems beyond POSIX and Windows.
• How port-for handles concurrent requests for port allocation in high-concurrency scenarios.

Package facts

Evidence: port_for-1.0.0-py3-none-any.whl

Keywords: port, posix

Tags

More Systems Administration packages