---
id: port-for
version: "1.0.0"
license: Copyright (c) 2012 Mikhail Korobov Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the… (full text in the JSON record)
license_treatment: permissive
maintenance: active
---

# port-for — Utility that helps with local TCP ports management. It can find an unused TCP localhost port and remember the association.

License: permissive · Maintenance: active · Downloads: 7.4M/mo

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

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

- License: Copyright (c) 2012 Mikhail Korobov Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 7.4M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

find unused tcp port, persistent port allocation, local port management, port binding utility, avoid ephemeral ports, remember port assignment, tcp port registry, port-management, cli-utility, local-development

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