optionalDependencies are packages npm will try to install but will not fail the whole install over if they cannot build. They are often platform specific binaries. For security, they still run install scripts, they can override a normal dependency of the same name, and they are easy to overlook in reviews.
What the docs say
The npm package.json documentation explains that the difference from regular dependencies is that build failures do not cause installation to fail. It is still your program's responsibility to handle the lack of the dependency. The omit optional option skips these packages.
One detail surprises people. Entries in optionalDependencies override entries of the same name in dependencies. If a package appears in both lists, the optional entry wins.
Where you see them
Many tools ship a main package plus several platform specific packages, one for each operating system and CPU, all listed as optional. Your install picks the one that matches your machine. That means a lockfile can contain entries for platforms you never run.
Security angles
- Scripts still run. An optional package can have install scripts like any other, so they belong in your script review.
- Silent failure hides problems. A failed optional install does not stop the build, so an expected package may be missing without a loud error.
- Override behavior. A package listed in both places resolves from the optional entry, which can differ from what a reviewer assumes.
- Scanner coverage. A scan that skips optional packages, or only looks at your current platform, will miss entries that matter to other developers or production images.
What to do
- List optionalDependencies in your project and in your most important direct dependencies.
- Confirm your scanner reads them from the lockfile rather than the installed tree.
- Check for names listed in both dependencies and optionalDependencies, and remove duplicates.
- Include optional packages when you review install scripts.
- In production images, decide whether to omit optional packages, and test the app both ways.
| Question | Answer from the docs |
|---|---|
| Does a build failure stop the install? | No for optional packages |
| Who handles the missing package? | Your code |
| Which wins if a name is in both lists? | optionalDependencies |
Common mistakes
A common one is marking a required package as optional to get past a flaky build. The install then succeeds without it and the app fails later in production. Another is trusting that a scan of your own machine covers everyone, when the optional entries installed differ per operating system and chip. Teams also forget that omitting optional packages in a container image changes behavior, so test the image you ship, not only the dev setup.
Quick check
Are optional dependencies skipped by default?
No. npm tries to install them. They are skipped only if you use the omit optional option.
Can optionalDependencies override dependencies?
Yes. If a package name is in both lists, the optionalDependencies entry overrides the other.
Safeguard reads the full lockfile into an SBOM so platform specific components appear too. Try the free scan at gold.safeguard.sh/scan, and see how to audit npm postinstall scripts safely.
Sources
Last reviewed: 19 October 2026.
