'vite' not recognized error

Problem statement

When working with Vite, you may encounter the error:

'vite' is not recognized as an internal or external command, operable program or batch file.

This error occurs when your system cannot locate the Vite executable, even after following the standard setup process:

npm create vite@latest my-project
cd my-project
npm install
npm run dev  # Error occurs here

Common causes

The error typically stems from one of these issues:

1. Missing dependencies: Vite wasn't properly installed in your node_modules
2. Environment configuration: NODE_ENV set to production prevents dev dependencies installation
3. Path issues: Special characters in directory paths or incorrect PATH configuration
4. Node.js version incompatibility: Using an unsupported Node.js version
5. Cache issues: Outdated or corrupted package-lock.json or node_modules

Solutions

1. Install dependencies properly

The most common solution is to ensure dependencies are correctly installed:

npm install

If the issue persists, clean install with:

rm -rf node_modules package-lock.json
npm install

2. Check environment variables

If NODE_ENV is set to production, npm won't install dev dependencies (including Vite):

# Check current NODE_ENV value
echo $NODE_ENV

# For development, unset or set to development
unset NODE_ENV  # Unix systems
set NODE_ENV=development  # Windows

# Alternatively, force install dev dependencies
npm install --include dev

3. Verify Node.js version compatibility

Vite requires Node.js version 14.18+ or 16+. Check your version:

node -v

If you need to change versions, use NVM (Node Version Manager):

# Install NVM (if not already installed)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
source ~/.nvm/nvm.sh

# Install and use Node.js 18
nvm install 18
nvm use 18

# Reinstall dependencies
npm install

4. Check for path issues

Special characters in directory paths can cause issues:

• Avoid colons (😃, ampersands (&), or slashes (/) in folder names
• Use simple, alphanumeric directory names
• Keep project paths short and avoid nested directories

5. Manual Vite installation

If Vite isn't in your dependencies, install it explicitly:

# As dev dependency (recommended)
npm install vite --save-dev

# Or globally (not recommended for projects)
npm install -g vite

6. Verify package.json scripts

Ensure your package.json has the correct scripts section:

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}

If path issues persist, you can reference Vite directly:

{
  "scripts": {
    "dev": "./node_modules/.bin/vite",
    "build": "./node_modules/.bin/vite build"
  }
}

7. Alternative package managers

Try using alternative package managers if npm continues to have issues:

# Using yarn
yarn install
yarn dev

# Using pnpm
pnpm install
pnpm dev

Troubleshooting checklist

When facing the "vite not recognized" error, follow this checklist:

1. ✅ Run npm install to ensure dependencies are installed
2. ✅ Check Node.js version compatibility (node -v)
3. ✅ Verify NODE_ENV is not set to production
4. ✅ Examine directory path for special characters
5. ✅ Check package.json for correct script definitions
6. ✅ Try clean installation: delete node_modules and package-lock.json
7. ✅ Consider using a different Node.js version via NVM

WARNING

Avoid installing Vite globally for project development. Project-specific dependencies ensure consistency across environments and prevent version conflicts.

TIP

If you switch between Node.js versions frequently or work on multiple projects, using NVM (Node Version Manager) helps manage different Node versions seamlessly.

When to seek additional help

If none of these solutions work:

1. Check the Vite troubleshooting guide
2. Verify there are no network or proxy issues affecting package installation
3. Ensure you have proper permissions to install packages globally (if using that approach)
4. Consult the Vite community discord or GitHub issues for similar problems

Most "vite not recognized" errors are resolved by ensuring proper dependency installation and environment configuration. The solutions above cover the vast majority of cases encountered by developers.