{"id":13454762,"url":"https://github.com/sindresorhus/get-port","last_synced_at":"2026-04-01T22:56:57.137Z","repository":{"id":15753329,"uuid":"18492045","full_name":"sindresorhus/get-port","owner":"sindresorhus","description":"Get an available TCP port","archived":false,"fork":false,"pushed_at":"2024-03-20T08:09:13.000Z","size":55,"stargazers_count":900,"open_issues_count":5,"forks_count":65,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-05-07T09:47:28.513Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sindresorhus.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"github":"sindresorhus","open_collective":"sindresorhus","buy_me_a_coffee":"sindresorhus","custom":"https://sindresorhus.com/donate"}},"created_at":"2014-04-06T15:06:52.000Z","updated_at":"2025-05-06T13:01:42.000Z","dependencies_parsed_at":"2023-09-27T09:48:47.567Z","dependency_job_id":"730db6ea-74f8-49ce-a2ce-bb0c56a1a429","html_url":"https://github.com/sindresorhus/get-port","commit_stats":{"total_commits":66,"total_committers":21,"mean_commits":3.142857142857143,"dds":"0.33333333333333337","last_synced_commit":"5c3cfe828bac345fb30b13211164708d97cb033a"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sindresorhus%2Fget-port","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sindresorhus%2Fget-port/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sindresorhus%2Fget-port/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sindresorhus%2Fget-port/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sindresorhus","download_url":"https://codeload.github.com/sindresorhus/get-port/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253619898,"owners_count":21937257,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T08:00:57.745Z","updated_at":"2026-04-01T22:56:57.130Z","avatar_url":"https://github.com/sindresorhus.png","language":"JavaScript","funding_links":["https://github.com/sponsors/sindresorhus","https://opencollective.com/sindresorhus","https://buymeacoffee.com/sindresorhus","https://sindresorhus.com/donate"],"categories":["Packages","JavaScript","Repository","包","Fingerprint","Uncategorized","Network","目录","Number","Node.js"],"sub_categories":["Network","网络","Port","Uncategorized","Terminal"],"readme":"# get-port\n\n\u003e Get an available [TCP port](https://en.wikipedia.org/wiki/Port_(computer_networking)).\n\n## Install\n\n```sh\nnpm install get-port\n```\n\n## Usage\n\n```js\nimport getPort from 'get-port';\n\nconsole.log(await getPort());\n//=\u003e 51402\n```\n\nPass in a preferred port:\n\n```js\nimport getPort from 'get-port';\n\nconsole.log(await getPort({port: 3000}));\n// Will use 3000 if available, otherwise fall back to a random port\n```\n\nPass in an array of preferred ports:\n\n```js\nimport getPort from 'get-port';\n\nconsole.log(await getPort({port: [3000, 3001, 3002]}));\n// Will use any element in the preferred ports array if available, otherwise fall back to a random port\n```\n\nUse the `portNumbers()` helper in case you need a port in a certain range:\n\n```js\nimport getPort, {portNumbers} from 'get-port';\n\nconsole.log(await getPort({port: portNumbers(3000, 3100)}));\n// Will use any port from 3000 to 3100, otherwise fall back to a random port\n```\n\n## API\n\n### getPort(options?)\n\nReturns a `Promise` for a port number.\n\n#### options\n\nType: `object`\n\n##### port\n\nType: `number | Iterable\u003cnumber\u003e`\n\nA preferred port or an iterable of preferred ports to use.\n\n##### exclude\n\nType: `Iterable\u003cnumber\u003e`\n\nPorts that should not be returned.\n\nYou could, for example, pass it the return value of the `portNumbers()` function.\n\n##### reserve\n\nType: `boolean`\\\nDefault: `false`\n\nReserve the port so that it's locked for the lifetime of the process instead of the default 15-30 seconds.\n\nThis is useful when there is a long delay between getting the port and actually binding to it, such as in long-running test suites.\n\nReserved ports are locked globally by port number for the current process, even if you looked them up with a specific `host` or `ipv6Only` option.\n\nUse [`clearLockedPorts()`](#clearlockedports) to release reserved ports.\n\n##### host\n\nType: `string`\n\nThe host on which port resolution should be performed. Can be either an IPv4 or IPv6 address.\n\nBy default, it checks availability on all local addresses defined in [OS network interfaces](https://nodejs.org/api/os.html#os_os_networkinterfaces). If this option is set, it will only check the given host.\n\n### portNumbers(from, to)\n\nGenerate port numbers in the given range `from`...`to`.\n\nReturns an `Iterable` for port numbers in the given range.\n\n```js\nimport getPort, {portNumbers} from 'get-port';\n\nconsole.log(await getPort({port: portNumbers(3000, 3100)}));\n// Will use any port from 3000 to 3100, otherwise fall back to a random port\n```\n\n#### from\n\nType: `number`\n\nThe first port of the range. Must be in the range `1024`...`65535`.\n\n#### to\n\nType: `number`\n\nThe last port of the range. Must be in the range `1024`...`65535` and must be greater than `from`.\n\n### clearLockedPorts()\n\nClear the internal cache of locked ports, including any ports locked with the [`reserve`](#reserve) option.\n\nThis can be useful when you want the results to be unaffected by previous calls.\n\nPlease note that clearing the cache removes protection against [in-process race conditions](#beware).\n\n```js\nimport getPort, {clearLockedPorts} from 'get-port';\n\nconst port = [3000, 3001, 3002];\n\nconsole.log(await getPort({port}));\n//=\u003e 3000\n\nconsole.log(await getPort({port}));\n//=\u003e 3001\n\n// If you want the results to be unaffected by previous calls, clear the cache.\nclearLockedPorts();\n\nconsole.log(await getPort({port}));\n//=\u003e 3000\n```\n\n## Beware\n\nThere is a very tiny chance of a race condition if another process starts using the same port number as you in between the time you get the port number and you actually start using it.\n\n**In-process race conditions** (such as when running parallel Jest tests) are completely eliminated by a lightweight locking mechanism where returned ports are held for 15-30 seconds before being eligible for reuse. If the delay between getting a port and binding to it may exceed this window (for example, in long-running test suites), use the [`reserve`](#reserve) option to lock the port for the lifetime of the process.\n\n**Multi-process race conditions** are extremely rare and will result in an immediate `EADDRINUSE` error when attempting to bind to the port, allowing your application to retry.\n\n## Related\n\n- [get-port-cli](https://github.com/sindresorhus/get-port-cli) - CLI for this module\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsindresorhus%2Fget-port","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsindresorhus%2Fget-port","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsindresorhus%2Fget-port/lists"}