{"id":1858,"library":"port-for","title":"port-for: Local TCP Ports Management","description":"Port-for is a utility that assists with local TCP ports management. It can identify an unused TCP localhost port and maintain an association with a given identifier, ensuring that subsequent requests for the same ID return the same port number. The current version is 1.0.0, primarily functioning as a local port management tool.","status":"active","version":"1.0.0","language":"en","source_language":"en","source_url":"https://github.com/fizyk/port-for/","tags":["networking","ports","local development","utility","testing"],"install":[{"cmd":"pip install port-for","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python 3.10 or newer.","package":"python","optional":false}],"imports":[{"symbol":"available_ports","correct":"from port_for import available_ports"},{"symbol":"PortFor","correct":"from port_for import PortFor"}],"quickstart":{"code":"from port_for import available_ports, PortFor\n\n# Find an ephemeral available port (context manager ensures release)\nwith available_ports(5000) as port:\n    print(f\"Found available port (5000 or next): {port}\")\n\n# Use PortFor for persistent port assignment based on an ID\nport_manager = PortFor()\n\n# Assign a port for 'my-service' (will try 8000 first)\nmy_service_port = port_manager.forward_port(\"my-service\", 8000)\nprint(f\"Assigned port for 'my-service': {my_service_port}\")\n\n# Assign a port for 'another-service' (will try 9000 first)\nanother_service_port = port_manager.forward_port(\"another-service\", 9000)\nprint(f\"Assigned port for 'another-service': {another_service_port}\")\n\n# Subsequent calls with the same ID will return the same assigned port\nsame_service_port = port_manager.forward_port(\"my-service\", 8000) # 8000 is a suggestion, not a requirement\nprint(f\"Re-requested port for 'my-service' (should be {my_service_port}): {same_service_port}\")\n\n# To release a port (optional, happens on process exit by default)\nport_manager.release(\"another-service\")\nprint(\"Released port for 'another-service'\")","lang":"python","description":"This quickstart demonstrates finding an ephemeral available port using `available_ports` and managing persistent port assignments with `PortFor`. `PortFor` ensures that once a port is assigned to an ID, subsequent requests with the same ID return that same port."},"warnings":[{"fix":"Use a unique identifier with `PortFor` for each service that requires a stable port, or use `available_ports` for truly ephemeral port needs.","message":"The `PortFor` class is designed for *persistent* port assignments tied to an identifier, not for finding a random available port each time. If you need a new, unassociated port, you must use a new ID or `available_ports`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For critical multi-process initial port assignments with the same ID, consider external locking or a dedicated port server/coordinator to prevent potential race conditions, or ensure each process requests a unique ID.","message":"While `port-for` aims to manage local port persistence, in highly concurrent multi-process environments, there's a theoretical race condition when *initially* assigning a port for a new ID. If multiple processes simultaneously attempt to call `forward_port` with the *same new ID* for the very first time, careful synchronization might be required externally, as `port-for` primarily handles persistence within a single management context.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use the return value of `forward_port` for the actual assigned port, rather than assuming `default_port` was used.","message":"The `forward_port` method takes a `default_port` argument. This is a *suggestion* for the desired port, not a guarantee. If the `default_port` is already in use (or was assigned to another ID), `port-for` will find another available port. The returned port is what's assigned to the ID.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}