fix!: don't install man pages in system locations

owlstronaut · owlstronaut · commit e20424b01a2d · 2026-04-23T07:42:48.000-07:00
BREAKING CHANGE: npm no longer registers man pages with the system when installed globally. `man npm-install` will no longer work, but `npm help install` is unaffected.
diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
@@ -399,9 +399,11 @@ See [folders](/configuring-npm/folders#executables) for more info on executables
 
 ### man
 
-Specify either a single file or an array of filenames to put in place for the `man` program to find.
+> **Note:** As of npm v12, man pages are no longer registered with the system `man` program. This field is retained for backward compatibility with package metadata and tools that consume it, but `man <pkgname>` will not work after a global install. Use `npm help <pkgname>` instead where supported.
 
-If only a single file is provided, then it's installed such that it is the result from `man <pkgname>`, regardless of its actual filename.
+Specify either a single file or an array of filenames to include as man pages.
+
+If only a single file is provided, then it corresponds to `man <pkgname>`, regardless of its actual filename.
 For example:
 
 ```json
@@ -414,7 +416,7 @@ For example:
 }
 ```
 
-would link the `./man/doc.1` file in such that it is the target for `man foo`
+would associate the `./man/doc.1` file such that it is the target for `man foo`
 
 If the filename doesn't start with the package name, then it's prefixed.
 So, this:
@@ -432,10 +434,10 @@ So, this:
 }
 ```
 
-will create files to do `man foo` and `man foo-bar`.
+will correspond to `man foo` and `man foo-bar`.
 
 Man files must end with a number, and optionally a `.gz` suffix if they are compressed.
-The number dictates which man section the file is installed into.
+The number dictates which man section the file belongs to.
 
 ```json
 {
@@ -469,7 +471,7 @@ If you want to specify individual files, use `bin`, and for all the files in an
 #### directories.man
 
 A folder that is full of man pages.
-Sugar to generate a "man" array by walking the folder.
+Sugar to generate a "man" array by walking the folder. See the note on [`man`](#man) above: as of npm v12, these are no longer installed into the system `man` path.
 
 ### repository
 
diff --git a/package.json b/package.json
@@ -32,10 +32,6 @@
   "bugs": {
     "url": "https://github.com/npm/cli/issues"
   },
-  "directories": {
-    "doc": "./doc",
-    "man": "./man"
-  },
   "main": "./index.js",
   "bin": {
     "npm": "bin/npm-cli.js",
diff --git a/tap-snapshots/test/lib/commands/publish.js.test.cjs b/tap-snapshots/test/lib/commands/publish.js.test.cjs
@@ -123,10 +123,6 @@ Object {
     "url": "https://github.com/npm/cli/issues",
   },
   "description": "a package manager for JavaScript",
-  "directories": Object {
-    "doc": "./doc",
-    "man": "./man",
-  },
   "exports": Object {
     ".": Array [
       Object {
@@ -153,91 +149,6 @@ Object {
   ],
   "license": "Artistic-2.0",
   "main": "./index.js",
-  "man": Array [
-    "man/man1/npm-access.1",
-    "man/man1/npm-audit.1",
-    "man/man1/npm-bugs.1",
-    "man/man1/npm-cache.1",
-    "man/man1/npm-ci.1",
-    "man/man1/npm-completion.1",
-    "man/man1/npm-config.1",
-    "man/man1/npm-dedupe.1",
-    "man/man1/npm-deprecate.1",
-    "man/man1/npm-diff.1",
-    "man/man1/npm-dist-tag.1",
-    "man/man1/npm-docs.1",
-    "man/man1/npm-doctor.1",
-    "man/man1/npm-edit.1",
-    "man/man1/npm-exec.1",
-    "man/man1/npm-explain.1",
-    "man/man1/npm-explore.1",
-    "man/man1/npm-find-dupes.1",
-    "man/man1/npm-fund.1",
-    "man/man1/npm-get.1",
-    "man/man1/npm-help-search.1",
-    "man/man1/npm-help.1",
-    "man/man1/npm-init.1",
-    "man/man1/npm-install-ci-test.1",
-    "man/man1/npm-install-test.1",
-    "man/man1/npm-install.1",
-    "man/man1/npm-link.1",
-    "man/man1/npm-ll.1",
-    "man/man1/npm-login.1",
-    "man/man1/npm-logout.1",
-    "man/man1/npm-ls.1",
-    "man/man1/npm-org.1",
-    "man/man1/npm-outdated.1",
-    "man/man1/npm-owner.1",
-    "man/man1/npm-pack.1",
-    "man/man1/npm-ping.1",
-    "man/man1/npm-pkg.1",
-    "man/man1/npm-prefix.1",
-    "man/man1/npm-profile.1",
-    "man/man1/npm-prune.1",
-    "man/man1/npm-publish.1",
-    "man/man1/npm-query.1",
-    "man/man1/npm-rebuild.1",
-    "man/man1/npm-repo.1",
-    "man/man1/npm-restart.1",
-    "man/man1/npm-root.1",
-    "man/man1/npm-run.1",
-    "man/man1/npm-sbom.1",
-    "man/man1/npm-search.1",
-    "man/man1/npm-set.1",
-    "man/man1/npm-start.1",
-    "man/man1/npm-stop.1",
-    "man/man1/npm-team.1",
-    "man/man1/npm-test.1",
-    "man/man1/npm-token.1",
-    "man/man1/npm-trust.1",
-    "man/man1/npm-undeprecate.1",
-    "man/man1/npm-uninstall.1",
-    "man/man1/npm-unpublish.1",
-    "man/man1/npm-update.1",
-    "man/man1/npm-version.1",
-    "man/man1/npm-view.1",
-    "man/man1/npm-whoami.1",
-    "man/man1/npm.1",
-    "man/man1/npx.1",
-    "man/man5/folders.5",
-    "man/man5/install.5",
-    "man/man5/npm-global.5",
-    "man/man5/npm-json.5",
-    "man/man5/npmrc.5",
-    "man/man5/package-json.5",
-    "man/man5/package-lock-json.5",
-    "man/man7/config.7",
-    "man/man7/dependency-selectors.7",
-    "man/man7/developers.7",
-    "man/man7/logging.7",
-    "man/man7/orgs.7",
-    "man/man7/package-spec.7",
-    "man/man7/registry.7",
-    "man/man7/removal.7",
-    "man/man7/scope.7",
-    "man/man7/scripts.7",
-    "man/man7/workspaces.7",
-  ],
   "name": "npm",
   "readmeFilename": "README.md",
   "repository": Object {
diff --git a/test/lib/commands/publish.js b/test/lib/commands/publish.js
@@ -813,7 +813,7 @@ t.test('manifest', async t => {
   }
   delete manifest.gitHead
 
-  manifest.man.sort()
+  manifest.man?.sort()
 
   t.matchSnapshot(manifest, 'manifest')
 })

Original file line number	Diff line number	Diff line change
`@@ -813,7 +813,7 @@ t.test('manifest', async t => {`
`813`	`813`	`}`
`814`	`814`	`delete manifest.gitHead`
`815`	`815`
`816`		`- manifest.man.sort()`
	`816`	`+ manifest.man?.sort()`
`817`	`817`
`818`	`818`	`t.matchSnapshot(manifest, 'manifest')`
`819`	`819`	`})`