Heuristic:Cypress io Cypress Global Install Warning
| Knowledge Sources | |
|---|---|
| Domains | Installation, Best_Practices |
| Last Updated | 2026-02-12 01:00 GMT |
Overview
Always install Cypress as a per-project devDependency rather than globally to avoid version conflicts and ensure reproducible CI builds.
Description
The Cypress CLI actively warns users when it detects a global installation. Global installs create version conflicts across projects, prevent lockfile-based reproducibility, and can cause subtle test failures when the global binary version diverges from what a project expects. The recommended pattern is `npm install --save-dev cypress` per project.
Usage
Apply this heuristic whenever setting up a new Cypress project or troubleshooting installation issues. If `cypress info` shows a globally installed binary, migrate to a per-project devDependency immediately.
The Insight (Rule of Thumb)
- Action: Install Cypress as a devDependency: `npm install --save-dev cypress`
- Value: Never use `npm install -g cypress`
- Trade-off: Each project has its own copy of the Cypress binary (cached globally by version, so disk impact is minimal)
Reasoning
Global installations create "works on my machine" scenarios where different projects silently use different Cypress versions. The Cypress binary is cached per-version in `~/.cache/Cypress/`, so per-project installs share the same binary cache. The CLI explicitly checks `is-installed-globally` and emits a warning with remediation steps.
Code Evidence
Global install detection from `cli/lib/tasks/install.ts:48-63`:
const displayCompletionMsg = (): void => {
if (util.isInstalledGlobally()) {
logger.log()
logger.warn(stripIndent`
${logSymbols.warning} Warning: It looks like you've installed Cypress globally.
The recommended way to install Cypress is as a devDependency per project.
You should probably run these commands:
- ${chalk.cyan('npm uninstall -g cypress')}
- ${chalk.cyan('npm install --save-dev cypress')}
`)
return
}
}