Skip to main content

Utility that helps with local TCP ports managment. It can find an unused TCP localhost port and remember the association.

Project description

port-for is a command-line utility and a python library that helps with local TCP ports managment.

It can find an unused TCP localhost port and remember the association.

This can be useful when you are installing a stack of software with multiple parts needing port numbers.


If you’re looking for a temporary port then socket.bind((host, 0)) is your best bet:

>>> import socket
>>> s = socket.socket()
>>> s.bind(("", 0))
>>> s.getsockname()
('', 54485)

port-for is necessary when you need persistent free local port number.

port-for is the exact opposite of s.bind((host, 0)) is sense that it shouldn’t return ports that s.bind((host, 0)) may return (because such ports are likely to be temporary reassigned by OS).

There are several rules port-for is trying to follow to find and return a new unused port:

  1. Port must be unused: port-for checks this by trying to connect to the port and to bind to it.
  2. Port must be IANA unassigned and otherwise not well-known: this is acheived by maintaining unassigned ports list (parsed from IANA and Wikipedia).
  3. Port shouldn’t be inside ephemeral port range. This is important because ports from ephemeral port range can be assigned temporary by OS (e.g. by machine’s IP stack) and this may prevent service restart in some circumstances. gimme_port doesn’t return ports from ephemeral port ranges configured at the current machine.
  4. Other heuristics are also applied: port-for tries to return a port from larger port ranges; it also doesn’t return ports that are too close to well-known ports.



sudo easy_install port-for

Script usage

port-for <foo> script finds an unused port and associates it with <foo>. Subsequent calls will return the same port number.

This utility doesn’t actually bind the port or otherwise prevents the port from being taken by another software. It however tries to select a port that is less likely to be used by another software (and that is unused at the time of calling of course). Utility also makes sure that port-for bar won’t return the same port as port-for foo on the same machine.

$ sudo port-for foo

$ sudo port-for foo

You may also want to prefix your app name:

$ sudo port-for instance1.apache

Please note that port-for script requires read and write access to /etc/port-for.conf so sudo may be necessary in order to run it.

Library usage

>>> import port_for
>>> port_for.select_random()

>>> port_for.select_random()

>>> 80 in port_for.available_good_ports()

Dig into source code for more.


Development happens at github and bitbucket:

The issue tracker is at github:

In order to run tests make sure you have tox installed, then type


from the source checkout.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for port-for, version 0.1
Filename, size File type Python version Upload date Hashes
Filename, size port-for-0.1.tar.gz (13.4 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page