portpicker

library1.6.0pypypi✓ verified 28d ago

Portpicker is a Python library designed to find unique available network ports. Version 1.6.0, released in August 2023, provides a straightforward API for identifying an open port, primarily intended for use in unittests or by test harnesses launching local servers. It is actively maintained by Google, with releases focusing on stability and Python 3 compatibility.

testing http-networking

pip install portpicker

github ↗package ↗

INSTALL

IMPORT

SIG · PORTPICKER

portpicker

testingpythonv1.6.0

Install

1.7s avg

Import

29ms

Disk

17MB

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.6.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.030s · 18.6MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.028s · 19MB

17MB installed

● package 17MB

Code

Verified usage

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

pick_unused_port

✓ import portpicker port = portpicker.pick_unused_port()

The primary function is directly available after importing the module.

This quickstart demonstrates how to use `portpicker.pick_unused_port()` to find an available network port and then attempts to bind a socket to it for immediate verification, mitigating the race condition risk.

import portpicker import socket try: # Attempt to pick an unused port test_port = portpicker.pick_unused_port() if test_port != 0: print(f"Picked unused port: {test_port}") # Verify the port can be bound to (reduces race condition window) s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) s.bind(('127.0.0.1', test_port)) s.listen(1) print(f"Successfully bound to and listening on port {test_port}") s.close() else: print("Failed to pick an unused port.") except Exception as e: print(f"An error occurred: {e}")

Debug

Known issues

gotchaA race condition exists between picking an unused port and your application binding to it. Another process could claim the port in the interim. For critical applications, consider binding to '0' to let the OS assign a port atomically or use a dedicated port server.

fix

After picking a port, immediately attempt to bind to it. For robust multi-process environments, deploy the optional port server and configure clients via the `PORTSERVER_ADDRESS` environment variable to coordinate port allocation.

affects: All versions

gotchaRepeated calls to `pick_unused_port()` without a port server are not guaranteed to return unique ports, especially on loaded systems. If multiple ports are required, a port server is recommended.

fix

For multiple unique ports, run the provided port server daemon on your host and set the `PORTSERVER_ADDRESS` environment variable (e.g., `@unittest-portserver`) in your test runners.

affects: All versions

deprecatedPython 2 support is limited to the 1.3.x release series. Later versions, including 1.6.0, are exclusively for Python 3.

fix

Ensure your project targets Python 3.6 or newer. If Python 2 compatibility is essential, pin to `portpicker==1.3.x`.

affects: 1.4.0 and higher

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'portpicker'

The `portpicker` library is not installed in the Python environment being used.

fix

Install the package using pip: `pip install portpicker`

AttributeError: module 'portpicker' has no attribute 'pick_unused_port'

This usually occurs if `portpicker` was installed but an older or corrupted version is present, or if there's a naming conflict with another module. It can also happen if attempting to call a non-existent function.

fix

Ensure `portpicker` is correctly installed and up-to-date (`pip install --upgrade portpicker`). Verify the function call is `portpicker.pick_unused_port()` as shown in the official documentation.

portpicker.pick_unused_port() returns None

The `pick_unused_port()` function returns `None` when it cannot find an available and unused network port within the default or specified range.

fix

Implement error handling for the `None` return value, e.g., `port = portpicker.pick_unused_port(); if port is None: raise RuntimeError('No unused port found!')`. This issue can also be mitigated by using a port server in highly concurrent test environments.

Upgrade

Version history

1.6.0latest on PyPI · released Aug 15, 2023

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

Bingbot

Resources

githubhttps://github.com/google/python_portpicker ↗

packagehttps://pypi.org/project/portpicker/ ↗