portpicker

What it is and what it does

Portpicker is a utility for finding an unused network port on the local host. It exposes a simple `pick_unused_port()` function that returns an available port number, and can also be invoked from the command line or as a Python module. The package is designed primarily for test automation, where you need to dynamically allocate ports without conflicts.

The library depends on psutil to check port availability. The documentation acknowledges a fundamental race condition: a port may be selected as free but claimed by another process before your code binds to it. For single-threaded test runs this is usually acceptable, but for loaded test hosts running many tests concurrently, the package includes an optional port server daemon that coordinates port allocation across all processes on the host, eliminating the race condition.

Use it for:

• Allocate a unique port dynamically in unit tests that start temporary servers.
• Obtain an available port from shell scripts without hardcoding port numbers.
• Run a port server daemon on test infrastructure to coordinate port allocation across concurrent test processes.
• Avoid port conflicts when spinning up multiple service instances in integration tests.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Finds and returns an unused network port on the local host, available as a Python function or command-line tool for use in test automation and shell scripts.

Yes, for test automation and development. The package is stable and has no known vulnerabilities, with low install friction. However, the repository is archived and unmaintained—if you encounter a bug or need a feature, you will need to fork or find an alternative. For production port coordination at scale, evaluate the included port server carefully or consider running it in a controlled test environment first.

Install

portpicker on PyPI

pip install portpicker

uv add portpicker

poetry add portpicker

Installing portpicker

Before you install

Low friction install with a single runtime dependency (psutil). Maintenance is inactive—the repository is archived and the last release was 2023-08-15—but the package is marked as Production/Stable and has been in use since 2015.

License in practice

Licensed under Apache 2.0 (permissive), so you can use, modify, and distribute it freely in commercial and private projects without restriction.

Quickstart

import portpicker
test_port = portpicker.pick_unused_port()

# Or from command line:
# python3 -m portpicker $$

Requires Python 3.6 or later. Race condition exists between port selection and binding; for production use, the documentation recommends running a port server daemon (included) and setting PORTSERVER_ADDRESS=@unittest-portserver.

Verify before relying

• Whether the port server daemon included in the package is production-ready or still considered experimental.
• Current state of the repository and whether critical bug fixes are still accepted despite archival status.
• Whether the race condition between picking a port and binding to it remains acceptable for modern test workloads.

Package facts

Evidence: portpicker-1.6.0-py3-none-any.whl

Tags

More Testing packages