getopts

library1.0.5jsnpmunverified

getopts is a lightweight and performant CLI argument parser for Node.js, currently at stable version 2.3.0. It aims to be a drop-in replacement for `minimist` and similar libraries, distinguishing itself through its small footprint (180 LOC), zero dependencies, and significantly faster parsing speeds, reportedly up to 6 times faster than alternatives. The library follows established utility conventions for argument parsing, providing sane defaults for common CLI patterns. It transitioned to ES modules in version 2.3.0 and has shipped TypeScript types since 2.1.1, facilitating modern JavaScript and TypeScript development workflows. Releases are generally driven by new features, bug fixes, and maintenance, with a recent focus on ESM migration.

http-networking

npm install getopts

github ↗package ↗

INSTALL

IMPORT

SIG · GETOPTS

getopts

http-networkingjavascriptv1.0.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

getopts

✓ import getopts from 'getopts'

✗ const getopts = require('getopts')

Since v2.3.0, getopts is an ES module only. CommonJS `require` will fail.

Options

✓ import type { Options } from 'getopts'

For TypeScript users, import the `Options` interface to type the configuration object.

Demonstrates parsing command-line arguments, including aliases and explicit type definitions for options.

import getopts from "getopts"; const args = process.argv.slice(2); const options = getopts(args, { alias: { output: ["o", "f"], type: "t", }, boolean: ["verbose"], string: ["name"] }); console.log("Parsed options:", options); // Example usage: node your-script.js --type=module -o main.js *.{js,json} --name="My App" -v // Expected output: { _: ['*.{js,json}'], output: 'main.js', type: 'module', o: 'main.js', f: 'main.js', t: 'module', name: 'My App', verbose: true }

Debug

Known issues

breakingVersion 2.3.0 migrated getopts to be an ES module (ESM) only. Projects using CommonJS `require()` will encounter `ReferenceError: require is not defined` or similar import errors.

fix

Migrate your project to use ES modules (`import`) or switch to dynamic `import('getopts')` if staying in CommonJS. Ensure your `package.json` specifies `"type": "module"` or uses `.mjs` file extensions for ESM.

affects: >=2.3.0

breakingVersion 2.0.0 introduced several behavioral changes, notably parsing a standalone hyphen (`-`) as an operand and explicitly ceasing mutation of the `options.default` object. Code relying on previous behavior for these aspects will break.

fix

Review your argument parsing logic for handling of single hyphens (`-`) and ensure `options.default` is not expected to be mutated. Make explicit copies if modification is necessary.

affects: >=2.0.0

gotchaOptions specified in `opts.string` or `opts.boolean` will be included in the result object with default values (`""` or `false`) even if they are not present in the `argv` array.

fix

Always check for the presence of an option's value if `undefined` is expected when the option is not provided. Filter out default values if they are indistinguishable from deliberately provided empty strings or `false`.

affects: >=2.0.0

gotchaShort option parsing can be ambiguous: `-a alpha` parses `a` as a string, but `-a` (followed by other options or end of arguments) parses `a` as a boolean. This can lead to unexpected type parsing.

fix

Always explicitly define option types using `opts.boolean: ['a']` or `opts.string: ['a']` to ensure consistent parsing behavior regardless of argument placement.

affects: >=1.0.0

gotchaIf an option is provided multiple times (e.g., `-x A -x B`), its value in the result object will be an array containing all occurrences in order, not just the last one.

fix

Anticipate array values for options that can legitimately be repeated. Process these arrays to consolidate or use all values as required by your application logic.

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: require is not defined in ES module scope

Attempting to import `getopts` using CommonJS `require()` syntax in an ES module environment after upgrading to v2.3.0.

fix

Change `const getopts = require('getopts')` to `import getopts from 'getopts'` and ensure your project is configured for ESM.

TypeError: getopts is not a function

This error can occur if you are trying to use a CommonJS `require()` for an ESM package, or if you are incorrectly trying to destructure a default export in a CommonJS context after v2.3.0.

fix

For ESM, use `import getopts from 'getopts'`. For CommonJS, either stick to v2.2.x or use dynamic import: `(await import('getopts')).default` to access the default export.

My command-line option is being parsed as a boolean (true/false) instead of a string value.

By default, short options without an immediately adjacent value or the `opts.string` configuration are treated as booleans. Similarly, long options without an `=` sign are boolean.

fix

To force an option to be parsed as a string, use `opts.string: ['optionName']`. To force it as a boolean (and push any subsequent argument into the operand array `_`), use `opts.boolean: ['optionName']`.

My default options object is being modified after parsing.

Prior to v2.0.0, `getopts` might have mutated the `options.default` object. Since v2.0.0, it explicitly does not.

fix

Ensure you are on `getopts@2.0.0` or newer. If you need to modify the default options based on parsed arguments, create a deep copy of your default options object before passing it to `getopts`.

Upgrade

Version history

1.0.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/jorgebucaran/getopts ↗

packagehttps://www.npmjs.com/package/getopts ↗