# portfinder

> A simple tool to find an open port on the current machine

Latest version **1.0.38** (published 2025-09-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install portfinder
pnpm add portfinder
yarn add portfinder
bun add portfinder
```

## Health

**Score 45/100 (D)** — status: stable.

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

Warnings: low downloads; no esm support.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 1.0.38 |
| Published | 2025-09-12 |
| First published | 2011-07-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >= 10.12 |
| Dependencies | 2 |
| Unpacked size | 22 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 899 |
| Author | Charlie Robbins |
| Maintainers | indexzero, eriktrom |
| Keywords | http, ports, utilities |

## Links

- npm: https://www.npmjs.com/package/portfinder
- Repository: https://github.com/http-party/node-portfinder
- Homepage: https://github.com/http-party/node-portfinder#readme
- Issues: https://github.com/http-party/node-portfinder/issues
- npm.io page: https://npm.io/package/portfinder

## Dependencies (2)

- [async](https://npm.io/package/async.md) ^3.2.6
- [debug](https://npm.io/package/debug.md) ^4.3.6

## Recent versions

- 1.0.38 (latest) — 2025-09-12
- 1.0.37 — 2025-04-28
- 1.0.36 — 2025-04-14
- 1.0.35 — 2025-03-14
- 1.0.34 — 2025-03-11
- 1.0.33 — 2025-02-26
- 1.0.32 — 2022-08-13
- 1.0.31 — 2022-08-13
- 1.0.30 — 2022-08-13
- 1.0.29 — 2022-08-06
- 1.0.28 — 2020-07-29
- 1.0.27 — 2020-07-20
- 1.0.26 — 2020-04-28
- 1.0.25 — 2019-10-15
- 1.0.24 — 2019-09-05
- … 29 more at https://npm.io/package/portfinder/versions

## README

# node-portfinder

[![CI](https://github.com/http-party/node-portfinder/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/http-party/node-portfinder/actions/workflows/ci.yml)

## Installation

You can install `portfinder` using a package manager like npm, yarn, or bun:

``` bash
npm install portfinder
```

## Usage
The `portfinder` module has a simple interface:

``` js
const portfinder = require('portfinder');

portfinder.getPort(function (err, port) {
  //
  // `port` is guaranteed to be a free port
  // in this scope.
  //
});
```

Or using promises:

``` js
const portfinder = require('portfinder');

portfinder.getPortPromise()
  .then((port) => {
    //
    // `port` is guaranteed to be a free port
    // in this scope.
    //
  })
  .catch((err) => {
    //
    // Could not get a free port, `err` contains the reason.
    //
  });
```

### Ports search scope

By default `portfinder` will start searching from `8000` and scan until maximum port number (`65535`) is reached.

You can change this globally by setting:

```js
portfinder.setBasePort(3000);    // default: 8000
portfinder.setHighestPort(3333); // default: 65535
```

or by passing optional options object on each invocation:

```js
portfinder.getPort({
  port: 3000,    // minimum port
  stopPort: 3333 // maximum port
}, callback);
```

## Run Tests
``` bash
npm test
```

#### Author: [Charlie Robbins][0]
#### Author/Maintainer: [Erik Trom][1]
#### License: MIT/X11
[0]: http://nodejitsu.com
[1]: https://github.com/eriktrom

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