Why Is the Vite Command Not Recognized? Fixing npm run dev Errors

The vite command fails when the local binary wrapper is missing from node_modules/.bin, usually because dependencies were not installed, Vite was excluded by production-only flags, or the command is being run from the wrong directory.

When you install Vite and attempt to start the development server with npm run dev, seeing "vite is not recognized as an internal or external command" indicates that Node cannot resolve the CLI binary. According to the vitejs/vite source code, this binary is created during installation based on a specific declaration in the package configuration. Understanding how this mechanism works allows you to diagnose and fix the resolution failure quickly.

How Vite Registers the CLI Command

The Vite package exposes its command-line interface through the bin field in packages/vite/package.json. This configuration instructs npm how to create the executable that your scripts invoke.

The Binary Declaration in package.json

In the Vite repository, the binary is defined at lines 8-10 of packages/vite/package.json:

{
  "bin": {
    "vite": "bin/vite.js"
  }
}

This mapping tells npm that when you type vite, it should execute the bin/vite.js file inside the installed Vite package.

How npm Creates the vite Executable

During npm install, the package manager generates a wrapper script at node_modules/.bin/vite (or vite.cmd on Windows). This wrapper executes the actual JavaScript entry point. The npm run dev command defined in your project's package.json relies on this wrapper being present:

{
  "scripts": {
    "dev": "vite"
  }
}

As seen in packages/create-vite/template-react/package.json at lines 5-9, starter templates reference the vite binary directly. If node_modules/.bin is not populated, the script fails with a command not found error.

Common Causes for "vite command not recognized"

When the binary wrapper is missing or inaccessible, Node cannot resolve the vite command. These specific failure modes are common in the vitejs/vite ecosystem.

Missing Dependencies or Incomplete Installation

If node_modules/.bin/vite does not exist, you likely skipped the installation step or it failed silently. The directory node_modules/.bin should contain the vite wrapper after a successful install.

Running Commands from the Wrong Directory

Node resolves binaries relative to the current working directory. If you run npm run dev from a subdirectory instead of the project root (where package.json resides), npm cannot locate node_modules/.bin/vite.

Production-Only Installation Excludes Dev Dependencies

Vite is typically listed under devDependencies. If you installed with npm install --production or set NODE_ENV=production, npm skips dev dependencies, leaving the vite binary uninstalled.

Global Installation PATH Issues

Installing Vite globally with npm i -g vite places the binary in a global directory that might not be in your system's PATH. Additionally, global installation bypasses the local node_modules/.bin resolution that npm run dev expects.

Corrupted node_modules Directory

Interrupted installations or filesystem issues can leave node_modules in a broken state where the .bin directory exists but the symlinks or wrappers are invalid.

Solutions to Restore the Vite Command

Follow these steps to resolve the "vite command not recognized" error based on the root cause.

1. Install Vite locally as a dev dependency. This is the recommended approach according to the vitejs/vite repository:

   npm install -D vite
   # or
   
   pnpm add -D vite
   # or
   
   yarn add -D vite

2. Verify the binary wrapper exists. Check that node_modules/.bin/vite was created:

   ls node_modules/.bin/vite
   # On Windows:
   
   dir node_modules\.bin\vite.cmd

3. Run the development server. Use the npm script defined in your package.json:

   npm run dev

   Alternatively, use npx to invoke the local binary without a script:

   npx vite

4. If using Windows PowerShell, ensure execution policies allow scripts, or use npx vite instead of direct binary calls.

5. For corrupted installations, delete node_modules and the lock file, then reinstall:

   rm -rf node_modules package-lock.json
   npm install

Summary

• The vite command is resolved from node_modules/.bin/vite, a wrapper created during installation based on the bin declaration in packages/vite/package.json.
• The "vite command not recognized" error occurs when this binary is missing due to incomplete installation, production-only installs, wrong working directories, or corrupted node_modules.
• Local installation (npm i -D vite) is the recommended fix, followed by running npm run dev or npx vite to ensure the binary is correctly resolved from the project directory.

Frequently Asked Questions

Why does npm run dev say vite is not recognized?

This happens when the vite binary is missing from node_modules/.bin. The error typically indicates that dependencies were not installed, Vite was installed with --production flags that skip devDependencies, or you are running the command from a directory that does not contain the node_modules folder. Run npm install from the project root to restore the binary.

Should I install Vite globally or locally?

You should install Vite locally as a dev dependency using npm install -D vite. According to the vitejs/vite source code, local installation ensures the binary is placed in node_modules/.bin where npm run dev can resolve it. Global installation (npm i -g vite) is not recommended for project-specific builds because it bypasses version locking and may cause PATH resolution issues.

How do I verify Vite is installed correctly?

Check that the binary wrapper exists at node_modules/.bin/vite (or node_modules/.bin/vite.cmd on Windows). You can also run npx vite --version to verify the CLI resolves correctly. If these commands fail, delete node_modules and your lock file, then run npm install again to recreate the binary links.

What if vite works on Mac/Linux but not Windows?

Windows uses different executable wrappers (vite.cmd for Command Prompt, vite.ps1 for PowerShell). If PowerShell execution policies block scripts, you will see "cannot be loaded because running scripts is disabled" rather than "command not recognized." Use npx vite instead of direct binary calls, or adjust PowerShell execution policies with Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}