How to fix npm ERR! code ETOOLARGE npm ERR! Package size exceeds maximum allowed size in npm

npmINTERMEDIATELOWUpdated Dec 3, 2025· 229 views

The ETOOLARGE error occurs when publishing an npm package that exceeds size limits. This usually happens when node_modules, test files, or large assets are accidentally included in the published package.

Quick fix

Fixes npm ERR! code ETOOLARGE npm ERR! Package size exceeds maximum allowed size

# Preview files without publishing
npm pack --dry-run

# Create tarball locally to inspect
npm pack

# List tarball contents
tar -tzf my-package-1.0.0.tgz | head -50

# Check tarball size
ls -lh *.tgz
  1. Diagnose what's being published
  2. Use the files field in package.json (recommended)
  3. Create .npmignore file (alternative approach)
  4. Verify package contents
npm — error
# Preview files without publishing
npm pack --dry-run
# Create tarball locally to inspect
npm pack
# List tarball contents
tar -tzf my-package-1.0.0.tgz | head -50
# Check tarball size
ls -lh *.tgz
npm ERR! code ETOOLARGE
npm ERR! Package size exceeds maximum allowed size

What this error means

This error indicates your npm package is too large for the registry to accept. Different registries have different limits: - npmjs.com: No explicit documented limit, but practical issues arise above 50MB - AWS CodeArtifact: 2 GB maximum - Azure Artifacts: 500 MB per package file - Private Verdaccio: Often defaults to 2 MB The most common cause is accidentally including files that shouldn't be published, like node_modules, test directories, or large assets.

Typical symptoms

  • npm publish fails with size-related error
  • Package tarball is unexpectedly large (hundreds of MB)
  • Installing your published package takes unusually long
  • npm pack creates a very large .tgz file

Common causes

  1. node_modules accidentally included in package
  2. Missing .npmignore file (falls back to .gitignore rules)
  3. Test directories and fixtures included
  4. Large assets (images, videos, binaries) in package
  5. Source maps (.map files) published with build output
  6. bundledDependencies including all transitive dependencies

How to fix "npm ERR! code ETOOLARGE npm ERR! Package size exceeds maximum allowed size"

1Diagnose what's being published

Check exactly what files will be included:

bash
# Preview files without publishing
npm pack --dry-run

# Create tarball locally to inspect
npm pack

# List tarball contents
tar -tzf my-package-1.0.0.tgz | head -50

# Check tarball size
ls -lh *.tgz

Look for node_modules/, test/, coverage/, or large files that shouldn't be included.

2Use the files field in package.json (recommended)

Whitelist only the files you want to publish:

json
{
  "name": "my-package",
  "version": "1.0.0",
  "files": [
    "dist/",
    "lib/",
    "index.js"
  ]
}

This is the safest approach—only explicitly listed files are published.

Automatically included (no need to list):
- package.json
- README (any case)
- LICENSE/LICENCE
- CHANGELOG

3Create .npmignore file (alternative approach)

Create .npmignore to exclude files:

bash
# .npmignore

# Version control
.git
.gitignore

# Dependencies (auto-ignored but explicit)
node_modules/

# Testing
test/
__tests__/
*.test.js
coverage/

# Development
.env
.vscode/
tsconfig.json
webpack.config.js

# Source maps
*.map

# CI/CD
.github/
.travis.yml

Important: When .npmignore exists, .gitignore is completely ignored for publishing.

4Verify package contents

After configuring, verify the package is now smaller:

bash
# Create tarball
npm pack

# Check file count
tar -tzf *.tgz | wc -l

# Check size
ls -lh *.tgz

# Extract and inspect
tar -xzf *.tgz
ls -la package/

A typical library should be under 1MB packed.

5Exclude source maps if building

If your package includes compiled/minified code, exclude source maps:

json
{
  "files": [
    "dist/index.js",
    "dist/index.d.ts"
  ]
}

Or in .npmignore:

bash
*.map

Source maps can be larger than the actual code.

6Use prepublishOnly to verify size

Add a script to check package size before every publish:

json
{
  "scripts": {
    "prepublishOnly": "npm pack --dry-run && npm run build"
  }
}

For automated size monitoring, use size-limit:

bash
npm install --save-dev size-limit @size-limit/file
json
{
  "size-limit": [
    {
      "path": "dist/index.js",
      "limit": "100 KB"
    }
  ]
}

Advanced notes

A real-world example: one developer accidentally published a 324MB package because they didn't have .npmignore and their .gitignore included dist/. Since .gitignore excluded dist/, npm fell back to including everything except .git and node_modules.

Ask yourself for each file: "Does the end user need this to use my package?" Typically publish only: compiled code (dist/, lib/), type definitions (*.d.ts), and essential metadata.

Use npx npm-packlist to see the exact list of files that will be packaged—helpful for debugging complex ignore patterns.

Frequently asked questions

What does "npm ERR! code ETOOLARGE npm ERR! Package size exceeds maximum allowed" mean?
This error indicates your npm package is too large for the registry to accept. com: No explicit documented limit, but practical issues arise above 50MB - AWS CodeArtifact: 2 GB maximum - Azure Artifacts: 500 MB per package file - Private Verdaccio: Often defaults to 2 MB The most common cause is accidentally including files that shouldn't be published, like node_modules, test directories, or large assets.
How do I fix "npm ERR! code ETOOLARGE npm ERR! Package size exceeds maximum allowed"?
The ETOOLARGE error occurs when publishing an npm package that exceeds size limits. This usually happens when node_modules, test files, or large assets are accidentally included in the published package.
What causes "npm ERR! code ETOOLARGE npm ERR! Package size exceeds maximum allowed"?
node_modules accidentally included in package Missing .npmignore file (falls back to .gitignore rules) Test directories and fixtures included
Is the "npm ERR! code ETOOLARGE npm ERR! Package size exceeds maximum allowed" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading