npm-unpublish

Unpublish a specific package version

$ npm unpublish [package_name]@[version]

$ npm unpublish [package_name] [[-f|--force]]

$ npm unpublish @[scope]/[package_name]

$ npm unpublish [package_name] --timeout [time_in_milliseconds]

$ npm unpublish [package_name] --dry-run

npm unpublish [options] [@scope]/[@]

--force
    Required to unpublish a package or version. This flag acknowledges the destructive and irreversible nature of the operation.

--dry-run
    Shows what would happen without actually performing the unpublish operation. Useful for testing.

--registry
    Specifies the registry to unpublish from. Defaults to the configured registry.

--loglevel
    Sets the level of logging output. Common levels include silent, error, warn, info, http, verbose, silly.

--json
    Outputs data in JSON format, useful for programmatic consumption.

--otp
    Required for unpublish operations if two-factor authentication (2FA) is enabled for the account.

The npm unpublish command removes a package or a specific version of a package from the registry. This action is typically permanent and irreversible on public registries like npmjs.com, with strict policies regarding package immutability. Unpublishing a package makes it unavailable for new installations or updates.

It's often used when a package was published in error, contains sensitive information, or is no longer maintained and needs to be completely withdrawn. Due to the destructive nature and potential for breaking existing projects, npm strongly discourages unpublishing, especially for packages with dependent users. For most packages on npmjs.com, unpublishing is only allowed within 72 hours of publication. After this period, only deprecation or removal of specific versions is generally possible via the npm deprecate command. The use of the --force flag is required for unpublishing, signifying the irreversible nature of the action.

Unpublishing a package, especially from npmjs.com, has significant limitations and implications:

Irreversibility: On public registries, once a package or version is unpublished, it is generally permanent and cannot be re-published with the same name or version.

72-Hour Window: For packages published on npmjs.com, unpublishing is usually only permitted within 72 hours of its initial publication. After this period, unpublishing is restricted, though specific versions might be removed under exceptional circumstances by contacting npm support.

Breaking Dependencies: Unpublishing a package can break existing projects that rely on it, leading to build failures or runtime errors for users who attempt to install or update dependencies.

Discouraged Practice: npm strongly discourages unpublishing. It recommends using npm deprecate instead to mark a package or version as deprecated, allowing users to migrate gracefully.

--force Requirement: The --force flag is mandatory to execute the unpublish command, serving as an explicit acknowledgment of the operation's destructive nature.

For most packages on npmjs.com, published versions are considered immutable after 72 hours. This policy is in place to ensure the stability and reliability of the Node.js and JavaScript ecosystems. While npm unpublish exists, its practical use on the public registry is limited to very specific scenarios, primarily within the initial 72-hour window post-publication.

The npm unpublish command has been a part of the npm CLI since its early versions, providing a mechanism to remove mistakenly published packages. However, its usage and the policies surrounding unpublishing have evolved significantly, particularly concerning the npmjs.com public registry. Initially, unpublishing was more lenient, but due to the potential for widespread breakage in the JavaScript ecosystem, npm introduced stricter policies around 2016, including the 72-hour window and the general discouragement of unpublishing in favor of deprecation. These changes aimed to ensure the stability and reliability of the npm ecosystem by making package versions effectively immutable after a short grace period. The requirement of the --force flag further emphasizes the deliberate and irreversible nature of the command.

npm publish(1), npm deprecate(1), npm owner(1), npm install(1)