# pick-port

> Get a free TCP or UDP port for the given IP address

Latest version **2.2.1** (published 2026-06-15) · ISC license · 0 weekly downloads

## Install

```sh
npm install pick-port
pnpm add pick-port
yarn add pick-port
bun add pick-port
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 2.2.1 |
| Published | 2026-06-15 |
| First published | 2018-01-30 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=22 |
| Dependencies | 1 |
| Unpacked size | 28 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 16 |
| Author | José Luis Millán |
| Maintainers | ibc, jmillan |
| Keywords | nodejs, network, port, tcp, udp |

## Links

- npm: https://www.npmjs.com/package/pick-port
- Repository: https://github.com/versatica/pick-port
- Homepage: https://github.com/versatica/pick-port#readme
- Issues: https://github.com/versatica/pick-port/issues
- Funding: https://opencollective.com/mediasoup
- npm.io page: https://npm.io/package/pick-port

## Dependencies (1)

- [debug](https://npm.io/package/debug.md) ^4.4.3

## Alternatives

- [@clerk/clerk-expo](https://npm.io/package/@clerk/clerk-expo.md) — 133.6K weekly downloads
- [@pothos/plugin-authz](https://npm.io/package/@pothos/plugin-authz.md) — 12.4K weekly downloads
- [@bounded-sh/client](https://npm.io/package/@bounded-sh/client.md) — 3.2K weekly downloads
- [@luigi-project/plugin-auth-oauth2](https://npm.io/package/@luigi-project/plugin-auth-oauth2.md) — 2.3K weekly downloads
- [@nocobase/plugin-verification](https://npm.io/package/@nocobase/plugin-verification.md) — 2.0K weekly downloads

## Recent versions

- 2.2.1 (latest) — 2026-06-15
- 2.2.0 — 2025-09-23
- 2.1.2 — 2025-08-14
- 2.1.1 — 2025-07-23
- 2.1.0 — 2024-06-21
- 2.0.1 — 2024-01-12
- 2.0.0 — 2024-01-09
- 1.0.1 — 2022-06-10
- 1.0.0 — 2019-06-19
- 0.1.0 — 2018-09-17
- 0.0.4 — 2018-02-12
- 0.0.3 — 2018-01-31
- 0.0.2 — 2018-01-30
- 0.0.1 — 2018-01-30

## README

# pick-port

[![][npm-shield-pick-port]][npm-pick-port]
[![][github-actions-shield-pick-port]][github-actions-pick-port]

Get an available TCP or UDP port for the given IP address.

```bash
$ npm install pick-port
```

## Usage

```ts
import { pickPort } from 'pick-port';
```

Get a random UDP port in IP 0.0.0.0:

```ts
const port = await pickPort({ type: 'udp' });
```

Get a TCP port in a specific IP and port range:

```ts
const port = await pickPort({
	type: 'tcp',
	ip: '192.168.10.111',
	minPort: 8000,
	maxPort: 9000,
});
```

## API

### async pickPort({ type, ip, minPort, maxPort, reserveTimeout }): Promise<number>

Resolves with an available port or rejects with an error otherwise.

| Option           | Type   | Description                                                                                                                                                  | Required | Default   |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------: | --------- |
| `type`           | String | 'udp' or 'tcp'.                                                                                                                                              |   Yes    |           |
| `ip`             | String | IPv4 or IPv6 address for which a free port is requested.                                                                                                     |    No    | '0.0.0.0' |
| `minPort`        | Number | Minimum port.                                                                                                                                                |    No    | 10000     |
| `maxPort`        | Number | Maximum port.                                                                                                                                                |    No    | 20000     |
| `reserveTimeout` | Number | Timeout in seconds during which a returned port will be internally reserved and prevented of being returned on a future call before the timeout has elapsed. |    No    | 5         |

- `@returns` {Number} A free port.

The `reserveTimeout` option provides the application with the required time to bind the free port before it is given again on a future call to this library.

## Authors

- José Luis Millán [[github](https://github.com/jmillan/)]
- Iñaki Baz Castillo [[website](https://inakibaz.me)|[github](https://github.com/ibc/)]

## License

[ISC](./LICENSE)

[npm-shield-pick-port]: https://img.shields.io/npm/v/pick-port.svg
[npm-pick-port]: https://npmjs.org/package/pick-port
[github-actions-shield-pick-port]: https://github.com/versatica/pick-port/actions/workflows/pick-port.yaml/badge.svg?branch=master
[github-actions-pick-port]: https://github.com/versatica/pick-port/actions/workflows/pick-port.yaml?query=branch%3Amaster

---
_Source: https://npm.io/package/pick-port · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._