How to fix npm ERR! code EINVALIDPACKAGENAME npm ERR! Invalid package name: name cannot start with a dot or underscore in npm

npmBEGINNERMEDIUMUpdated Dec 6, 2025· 120 views

The EINVALIDPACKAGENAME error occurs when your package name starts with a period (.) or underscore (_). Remove the leading character or use a scoped package name instead.

Quick fix

Fixes EINVALIDPACKAGENAME

// Invalid
{
  "name": ".my-package"
}

// Valid
{
  "name": "my-package"
}
  1. Fix your package name
  2. Remove .DS_Store files (macOS)
  3. Remove temporary npm directories
  4. Clean Angular compiler artifacts
npm — error
// Invalid
{
  "name": ".my-package"
}
// Valid
{
  "name": "my-package"
}
npm ERR! code EINVALIDPACKAGENAME
npm ERR! Invalid package name: name cannot start with a dot or underscore

What this error means

This error occurs when your package name begins with a dot (.) or underscore (_). npm prohibits these characters at the start of package names for several reasons: Names starting with dots are typically hidden files/directories on Unix systems (.gitignore, .env, .npmrc). If npm allowed packages with these names, they could conflict with configuration files or be accidentally hidden in file listings. Names starting with underscores were historically used for npm's internal purposes and are reserved for potential future use. The error often appears when system files like .DS_Store (macOS) or temporary directories are accidentally detected as packages during npm operations.

Typical symptoms

  • npm publish fails with 'cannot start with dot or underscore' error
  • Error during npm install referencing .DS_Store or similar
  • npm update -g fails with invalid package name
  • Corrupted node_modules contains directories starting with . or _
  • CI/CD pipeline fails during dependency installation
  • Error mentions __ngcc_entry_points__ or similar internal files

Common causes

  1. Package name in package.json starts with . or _
  2. .DS_Store files (macOS) detected as packages
  3. Temporary npm directories (.npm-*) left in node_modules
  4. Angular compiler artifacts (__ngcc_entry_points__)
  5. Manually edited package.json with invalid name
  6. Corrupted package-lock.json with invalid entries

How to fix "npm ERR! code EINVALIDPACKAGENAME npm ERR! Invalid package name: name cannot start with a dot or underscore"

1Fix your package name

Remove the leading dot or underscore from your package.json:

json
// Invalid
{
  "name": ".my-package"
}

// Valid
{
  "name": "my-package"
}

Or use a scoped name:

json
{
  "name": "@myorg/my-package"
}
2Remove .DS_Store files (macOS)

Delete macOS system files from your project and node_modules:

bash
# Remove from current directory and subdirectories
find . -name '.DS_Store' -type f -delete

# Remove from global npm directory
find /usr/local/lib/node_modules -name '.DS_Store' -type f -delete

# If using nvm
find ~/.nvm -name '.DS_Store' -type f -delete

Add to .gitignore to prevent committing them:

bash
.DS_Store
3Remove temporary npm directories

Delete npm's temporary directories that may have been left behind:

bash
# Remove .npm-* directories from node_modules
rm -rf node_modules/.npm-*

# Remove from global directory
rm -rf /usr/local/lib/node_modules/.npm-*

These directories are created during installation and should be cleaned up automatically, but sometimes remain after interrupted installs.

4Clean Angular compiler artifacts

For Angular projects with __ngcc_entry_points__ errors:

bash
# Remove the artifact
rm -rf node_modules/__ngcc_entry_points__.json

# Clear Angular cache
rm -rf .angular

# Reinstall
rm -rf node_modules package-lock.json
npm install
5Clean install everything

If the issue persists, do a full clean reinstall:

bash
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

For global packages:

bash
npm cache clean --force
npm update -g

Advanced notes

Scoped packages (@scope/name) technically allow the package name part to start with a dot or underscore after the slash, but this is discouraged and may cause issues with some tools.

The .DS_Store problem is particularly common when:
- macOS users commit node_modules to git
- Shared network drives are used for development
- node_modules is copied between systems

To permanently prevent .DS_Store creation in a directory:

bash
defaults write com.apple.desktopservices DSDontWriteNetworkStores true

For CI/CD pipelines, always use npm ci instead of npm install to ensure a clean, reproducible installation that won't pick up stray files.

Frequently asked questions

What does "EINVALIDPACKAGENAME" mean?
) or underscore (_). npmrc). If npm allowed packages with these names, they could conflict with configuration files or be accidentally hidden in file listings.
How do I fix "EINVALIDPACKAGENAME"?
The EINVALIDPACKAGENAME error occurs when your package name starts with a period (.) or underscore (_). Remove the leading character or use a scoped package name instead.
What causes "EINVALIDPACKAGENAME"?
Package name in package.json starts with . or _ .DS_Store files (macOS) detected as packages Temporary npm directories (.npm-*) left in node_modules
Is the "EINVALIDPACKAGENAME" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading