1# Python portpicker module 2 3[](https://badge.fury.io/py/portpicker) 4 5[](https://travis-ci.org/google/python_portpicker) 6 7This module is useful for finding unused network ports on a host. If you need 8legacy Python 2 support, use the 1.3.x releases. 9 10This module provides a pure Python `pick_unused_port()` function. It can also be 11called via the command line for use in shell scripts. 12 13If your code can accept a bound TCP socket rather than a port number consider 14using `socket.bind(('localhost', 0))` to bind atomically to an available port 15rather than using this library at all. 16 17There is a race condition between picking a port and your application code 18binding to it. The use of a port server by all of your test code to avoid that 19problem is recommended on loaded test hosts running many tests at a time. 20 21Unless you are using a port server, subsequent calls to `pick_unused_port()` to 22obtain an additional port are not guaranteed to return a unique port. 23 24### What is the optional port server? 25 26A port server is intended to be run as a daemon, for use by all processes 27running on the host. It coordinates uses of network ports by anything using a 28portpicker library. If you are using hosts as part of a test automation cluster, 29each one should run a port server as a daemon. You should set the 30`PORTSERVER_ADDRESS=@unittest-portserver` environment variable on all of your 31test runners so that portpicker makes use of it. 32 33A sample port server is included. This portserver implementation works but has 34not spent time in production. If you use it with good results please report back 35so that this statement can be updated to reflect that. :) 36 37A port server listens on a unix socket, reads a pid from a new connection, tests 38the ports it is managing and replies with a port assignment port for that pid. A 39port is only reclaimed for potential reassignment to another process after the 40process it was originally assigned to has died. Processes that need multiple 41ports can simply issue multiple requests and are guaranteed they will each be 42unique. 43 44## Typical usage: 45 46```python 47import portpicker 48test_port = portpicker.pick_unused_port() 49``` 50 51Or from the command line: 52 53```bash 54TEST_PORT=`/path/to/portpicker.py $$` 55``` 56 57Or, if portpicker is installed as a library on the system Python interpreter: 58 59```bash 60TEST_PORT=`python3 -m portpicker $$` 61``` 62 63## DISCLAIMER 64 65This is not an official Google product (experimental or otherwise), it is just 66code that happens to be owned by Google. 67
){kind=link}
){kind=link}
){kind=link}