port-for

library1.0.0pypypi✓ verified 26d ago

Port-for is a utility that assists with local TCP ports management. It can identify an unused TCP localhost port and maintain an association with a given identifier, ensuring that subsequent requests for the same ID return the same port number. The current version is 1.0.0, primarily functioning as a local port management tool.

devops

pip install port-for

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · PORT-FOR

port-for

devopspythonv1.0.0

Install

1.5s avg

Import

37ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.040s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.034s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

available_ports

✓ from port_for import available_ports

PortFor

✓ from port_for import PortFor

This quickstart demonstrates finding an ephemeral available port using `available_ports` and managing persistent port assignments with `PortFor`. `PortFor` ensures that once a port is assigned to an ID, subsequent requests with the same ID return that same port.

from port_for import available_ports, PortFor # Find an ephemeral available port (context manager ensures release) with available_ports(5000) as port: print(f"Found available port (5000 or next): {port}") # Use PortFor for persistent port assignment based on an ID port_manager = PortFor() # Assign a port for 'my-service' (will try 8000 first) my_service_port = port_manager.forward_port("my-service", 8000) print(f"Assigned port for 'my-service': {my_service_port}") # Assign a port for 'another-service' (will try 9000 first) another_service_port = port_manager.forward_port("another-service", 9000) print(f"Assigned port for 'another-service': {another_service_port}") # Subsequent calls with the same ID will return the same assigned port same_service_port = port_manager.forward_port("my-service", 8000) # 8000 is a suggestion, not a requirement print(f"Re-requested port for 'my-service' (should be {my_service_port}): {same_service_port}") # To release a port (optional, happens on process exit by default) port_manager.release("another-service") print("Released port for 'another-service'")

port-for --version

Debug

Known issues

gotchaThe `PortFor` class is designed for *persistent* port assignments tied to an identifier, not for finding a random available port each time. If you need a new, unassociated port, you must use a new ID or `available_ports`.

fix

Use a unique identifier with `PortFor` for each service that requires a stable port, or use `available_ports` for truly ephemeral port needs.

affects: All versions

gotchaWhile `port-for` aims to manage local port persistence, in highly concurrent multi-process environments, there's a theoretical race condition when *initially* assigning a port for a new ID. If multiple processes simultaneously attempt to call `forward_port` with the *same new ID* for the very first time, careful synchronization might be required externally, as `port-for` primarily handles persistence within a single management context.

fix

For critical multi-process initial port assignments with the same ID, consider external locking or a dedicated port server/coordinator to prevent potential race conditions, or ensure each process requests a unique ID.

affects: All versions

gotchaThe `forward_port` method takes a `default_port` argument. This is a *suggestion* for the desired port, not a guarantee. If the `default_port` is already in use (or was assigned to another ID), `port-for` will find another available port. The returned port is what's assigned to the ID.

fix

Always use the return value of `forward_port` for the actual assigned port, rather than assuming `default_port` was used.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'port_for'

The 'port-for' library is not installed in your Python environment, or there is a typo in the import statement, or your script file is named 'port_for.py' which shadows the actual module.

fix

Install the library using pip: `pip install port-for`. If a typo, correct the import to `import port_for`. If shadowing, rename your script file.

AttributeError: module 'port_for' has no attribute 'some_non_existent_method'

You are trying to call a method or access an attribute that does not exist in the 'port_for' module (e.g., a typo in the function name) or has been removed/renamed in the version you are using. For example, 'get_available_port' was deprecated in favor of 'available_local_port' with a 'binding' argument.

fix

Consult the `port-for` documentation for the correct function names and their usage. For finding an available port, use `port_for.available_local_port()`.

OSError: [Errno 98] Address already in use

The underlying operating system reports that the port 'port-for' attempted to bind is already in use by another process. While `port-for` aims to find available ports, this can occur if you explicitly request a port that is occupied, or due to a race condition where another process claims the port between `port-for`'s check and its attempt to bind.

fix

Allow `port-for` to select a random available port by calling `port_for.available_local_port()` without the `port` argument. If you need a specific port, ensure no other application is using it, or use `netstat` (or `lsof` on Linux/macOS) to identify and stop the conflicting process.

TypeError: available_local_port() got an unexpected keyword argument 'id'

You are attempting to use the `id` keyword argument with the `available_local_port` function. The `id` argument was part of the deprecated `get_available_port` function and has been replaced by the `binding` argument in `available_local_port`.

fix

Replace the `id` argument with `binding`. For example, change `port_for.available_local_port(id='my_service')` to `port_for.available_local_port(binding='my_service')`.

Upgrade

Version history

1.0.0latest on PyPI · released Sep 30, 2025

Audit

Dependencies

pythonrequiredRequires Python 3.10 or newer.

Agent activity

20 hits · last 30 days

node

Resources

githubhttps://github.com/fizyk/port-for ↗

packagehttps://pypi.org/project/port-for/ ↗

changeloghttps://github.com/fizyk/port-for/blob/v1.0.0/CHANGES.rst ↗