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

> Fix the vite command not recognized error with npm run dev. Learn why your Vite binary is missing from node_modules bin and how to resolve installation or directory issues.

- Repository: [Vite/vite](https://github.com/vitejs/vite)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/vitejs/vite/blob/main/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`](https://github.com/vitejs/vite/blob/main/packages/vite/package.json):

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

```

This mapping tells npm that when you type `vite`, it should execute the [`bin/vite.js`](https://github.com/vitejs/vite/blob/main/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`](https://github.com/vitejs/vite/blob/main/package.json) relies on this wrapper being present:

```json
{
  "scripts": {
    "dev": "vite"
  }
}

```

As seen in [`packages/create-vite/template-react/package.json`](https://github.com/vitejs/vite/blob/main/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`](https://github.com/vitejs/vite/blob/main/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:

   ```bash
   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:

   ```bash
   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`](https://github.com/vitejs/vite/blob/main/package.json):

   ```bash
   npm run dev
   ```

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

   ```bash
   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:

   ```bash
   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`](https://github.com/vitejs/vite/blob/main/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`.