{"id":3218,"library":"portpicker","title":"Portpicker","description":"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.","status":"active","version":"1.6.0","language":"en","source_language":"en","source_url":"https://github.com/google/python_portpicker","tags":["networking","testing","ports","utility","tcp"],"install":[{"cmd":"pip install portpicker","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The primary function is directly available after importing the module.","symbol":"pick_unused_port","correct":"import portpicker\nport = portpicker.pick_unused_port()"}],"quickstart":{"code":"import portpicker\nimport socket\n\ntry:\n    # Attempt to pick an unused port\n    test_port = portpicker.pick_unused_port()\n    if test_port != 0:\n        print(f\"Picked unused port: {test_port}\")\n        # Verify the port can be bound to (reduces race condition window)\n        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)\n        s.bind(('127.0.0.1', test_port))\n        s.listen(1)\n        print(f\"Successfully bound to and listening on port {test_port}\")\n        s.close()\n    else:\n        print(\"Failed to pick an unused port.\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"A 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Repeated 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your project targets Python 3.6 or newer. If Python 2 compatibility is essential, pin to `portpicker==1.3.x`.","message":"Python 2 support is limited to the 1.3.x release series. Later versions, including 1.6.0, are exclusively for Python 3.","severity":"deprecated","affected_versions":"1.4.0 and higher"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}