It depends on who reads the file. The pnpm sbom command has an --exclude-peers flag that drops peer dependencies and anything reachable solely through them. Leave it off when you want a record of everything installed. Turn it on when automatic peer installation adds packages you do not consider part of your product.
What the documentation says
The pnpm sbom page lists --exclude-peers as an option that excludes peer dependencies and anything reachable solely through them, added in version 11.9.0, and says it is useful with auto-install-peers. Other scope options on the same page include --prod, which includes dependencies and optionalDependencies, --dev, which includes devDependencies, and --no-optional, which excludes optionalDependencies.
So there are several knobs that shrink or grow the file. Peer handling is one of them.
A quick definition
A peer dependency is a package that a library expects the host project to provide, instead of installing its own copy. A plugin for a framework is a typical example: the plugin needs the framework, and it declares that need as a peer. When a package manager is set to install peers automatically, it brings in packages that nobody listed in the host's own manifest.
What changes in the file
| Setting | Peers installed automatically | In the SBOM |
|---|---|---|
| Default | Yes | Included |
| Exclude peers | Yes | Removed, with anything reachable solely through them |
If a package is both a peer of one library and a direct dependency of your project, it stays, because it is reachable by another path. The flag removes solely what depends solely on the peer route.
A worked example
Suppose an application uses a charting plugin that declares a peer on a rendering library, and the project turns on automatic peer installation. Names are invented. The rendering library is not in the application's own dependency list. The plugin brings it in through the peer route.
Run the command twice and compare:
- Without the flag, the file lists the plugin and the rendering library and the rendering library's own dependencies.
- With the flag, the file lists the plugin but not the rendering library or the packages reachable solely through it.
Which one is right? Think about what the file is for. If it supports vulnerability management, the rendering library is installed and, if the app loads it, runs. Excluding it hides a package that could carry an advisory. If it supports a license review of what you chose, you might prefer to see solely direct choices. The right answer is the one that matches the purpose, and you should say which you chose.
Risks of excluding peers
- Hidden vulnerabilities. A peer that is installed and executed can be vulnerable. A file that omits it can say clean when it is not.
- Customer surprise. A customer who scans your deployed artifact finds packages missing from your SBOM and asks why.
- Drift. If someone later turns off automatic peer installation, the file changes meaning and nobody notices.
When excluding peers makes sense
- The file describes a library you publish, and peers are expected to come from the consumer. Listing them as your components could mislead readers into thinking you ship them.
- The peers are provided by the platform at runtime, and you want to avoid double counting.
- You publish two files, one with peers and one without, and label them clearly.
A recommended default
For an application you deploy, include peers. The file should describe what runs. For a library you publish, consider excluding peers and add a note that the consumer provides them. In both cases, put the flag in your script so the decision is explicit, and write one sentence in the cover note.
Verification steps
- Generate both versions of the file.
- Diff the component lists.
- For each package that disappears, decide whether you are comfortable not reporting it.
- Check that the root component type matches what you ship.
- Record the choice, the pnpm version and the date.
Interaction with other flags
Combine the peer flag with the production scope flag carefully. Production scope removes dev dependencies, and the peer flag removes the peer route. Together they can shrink the file a lot. After combining, compare against a full file to be sure you understand the difference. Safeguard can scan the resulting SBOM and dependencies, and the free scan at gold.safeguard.sh/scan lets you test both variants.
Communicating the choice to readers
Whichever way you go, tell the reader. A one line note in the cover letter is enough: this file includes peer dependencies installed automatically, or this file excludes them and the consumer provides them. Without the note, someone comparing your file with a scan of the installed tree will assume a mistake.
Reviewing the choice over time
Peer behavior depends on project settings and on the packages you use. A framework upgrade can turn a plain dependency into a peer or the reverse. Review the diff between the full and the excluded file once a quarter. If the gap grows, the excluded file may be hiding more than you intended, and it is time to revisit.
A worked comparison table
| Question | Include peers | Exclude peers |
|---|---|---|
| Does the file match the installed tree? | Closely | Not always |
| Is it good for vulnerability tracking? | Yes | Risk of gaps |
| Is it good for a published library? | Can overstate what you ship | Often clearer |
| Is it easy to explain to customers? | Yes | Needs a note |
Use the table as a conversation starter with your security and release owners, then record the decision where the SBOM script lives.
Try it yourself
Click through it at your own pace, or open it full screen.
Compare direct and transitive entries and think about which ones a customer would expect to see.
Quick check
What does --exclude-peers remove?
Peer dependencies and anything reachable solely through them, per the pnpm documentation.
Which pnpm version added the flag?
The docs say 11.9.0.
Should an application SBOM exclude peers?
Usually not. An application SBOM should describe what runs, and installed peers run.
Sources
Last reviewed: 19 October 2026.
