> For the complete documentation index, see [llms.txt](https://docs.sov.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sov.ai/api-reference/utils/port-manager.md).

# Port Manager

API reference for sovai.utils.port\_manager

**Module:** `sovai.utils.port_manager`

## Classes

### `PortManager`

```python
class PortManager
```

Manages the allocation of unique network ports for applications. Includes robust checks for port availability and can attempt to free ports.

**Attributes**

* `app_ports` (`Dict[str, int]`)
* `min_port`
* `max_port`

**Methods**

### `__init__()`

```python
def __init__(self, min_port: int = 8050, max_port: int = 8099)
```

Initializes the PortManager.

**Parameters**

| Parameter  | Type  | Description                                                                                                      |
| ---------- | ----- | ---------------------------------------------------------------------------------------------------------------- |
| `min_port` | `int` | The minimum port number in the range to assign. max\_port (int): The maximum port number in the range to assign. |

***

### `is_port_in_use()`

```python
def is_port_in_use(self, port: int) -> bool
```

Checks if a port is currently in use on the system. Tries to bind to the port; if it fails, the port is in use.

**Parameters**

| Parameter | Type  | Description               |
| --------- | ----- | ------------------------- |
| `port`    | `int` | The port number to check. |

**Returns**

bool: True if the port is in use, False otherwise.

***

### `kill_process_on_port()`

```python
def kill_process_on_port(self, port: int) -> bool
```

Finds and kills processes listening on the given port.

**Parameters**

| Parameter | Type  | Description                 |
| --------- | ----- | --------------------------- |
| `port`    | `int` | The port number to free up. |

**Returns**

bool: True if any process was attempted to be killed, False otherwise.

***

### `get_unique_port()`

```python
def get_unique_port(self, app_name: str) -> int
```

Gets a unique port for the given application name. If a port was already assigned to this app\_name in this session, tries to reuse it if free. Otherwise, finds a new free port in the defined range.

**Parameters**

| Parameter  | Type  | Description                                   |
| ---------- | ----- | --------------------------------------------- |
| `app_name` | `str` | The name of the application requiring a port. |

**Returns**

int: A unique port number.

***

### `release_port()`

```python
def release_port(self, app_name: str)
```

Releases a port associated with an app\_name, making it available for reuse by this manager. Note: This does not kill any process currently using the port system-wide.

**Parameters**

| Parameter  | Type  | Description                                               |
| ---------- | ----- | --------------------------------------------------------- |
| `app_name` | `str` | The name of the application whose port is to be released. |

***

***

## Functions

### `get_port_manager_instance()`

```python
def get_port_manager_instance(min_port: int = 8050, max_port: int = 8099) -> PortManager
```

Returns a cached singleton instance of PortManager. Allows customization of port range on first call.

**Parameters**

| Parameter  | Type  | Description                                                                                        |
| ---------- | ----- | -------------------------------------------------------------------------------------------------- |
| `min_port` | `int` | The minimum port number for the manager. max\_port (int): The maximum port number for the manager. |

**Returns**

PortManager: The singleton PortManager instance.

***

### `get_unique_port()`

```python
def get_unique_port(app_name: str, min_port: int = 8050, max_port: int = 8099) -> int
```

Gets a unique port for the given application name using the singleton PortManager. Port range can be specified, affecting the singleton on its first creation.

**Parameters**

| Parameter  | Type  | Description     |
| ---------- | ----- | --------------- |
| `app_name` | `str` | —               |
| `min_port` | `int` | Default: `8050` |
| `max_port` | `int` | Default: `8099` |

**Returns:** `int`

***

### `kill_process_on_port()`

```python
def kill_process_on_port(port: int, min_port: int = 8050, max_port: int = 8099) -> bool
```

Finds and kills processes listening on the given port using the singleton PortManager.

**Parameters**

| Parameter  | Type  | Description     |
| ---------- | ----- | --------------- |
| `port`     | `int` | —               |
| `min_port` | `int` | Default: `8050` |
| `max_port` | `int` | Default: `8099` |

**Returns:** `bool`

***

### `release_port()`

```python
def release_port(app_name: str, min_port: int = 8050, max_port: int = 8099)
```

Releases a port associated with an app\_name using the singleton PortManager.

**Parameters**

| Parameter  | Type  | Description     |
| ---------- | ----- | --------------- |
| `app_name` | `str` | —               |
| `min_port` | `int` | Default: `8050` |
| `max_port` | `int` | Default: `8099` |

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sov.ai/api-reference/utils/port-manager.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.