How to fix npm WARN publish npm WARN publish No README.md file found in npm

npmBEGINNERLOWUpdated Dec 5, 2025· 123 views

This warning appears when npm cannot find a README.md file in your package root directory during publication. While not required to publish, npm expects packages to include a README because it serves as the primary documentation displayed on npmjs.com.

Quick fix

Fixes npm WARN publish npm WARN publish No README.md file found

# My Package

A useful utility for X.

## Installation

\`\`\`bash
npm install my-package
\`\`\`

## Usage

\`\`\`javascript
const myPackage = require('my-package');
// example code
\`\`\`

## License

MIT
  1. Create README.md in package root
  2. Add essential content
  3. Include recommended sections
  4. Verify .npmignore doesn't exclude README
npm — error
# My Package
A useful utility for X.
## Installation
\`\`\`bash
npm install my-package
\`\`\`
## Usage
\`\`\`javascript
const myPackage = require('my-package');
// example code
\`\`\`
## License
MIT
npm WARN publish npm WARN publish No README.md file found

What this error means

This warning appears when npm cannot find a README.md file in your package root directory during publication or installation. While technically not required to publish a package, npm expects published packages to include a README file because it serves as the primary documentation displayed on the package's npmjs.com page. The registry stores the first 64KB of the README content and renders it as GitHub Flavored Markdown. Without a README, your package page on npmjs.com shows "This package does not have a README" message, reducing discoverability and user confidence. This is a warning, not an error—your package will still publish, but it signals incomplete package metadata.

Typical symptoms

  • Warning message appears during npm publish
  • Package page on npmjs.com shows 'This package does not have a README'
  • Users see no documentation on the package page when searching npmjs.com
  • Package quality score on npmjs.com is reduced

Common causes

  1. No README file in package root directory
  2. README in .npmignore or excluded by files field
  3. README file has wrong name (README.txt instead of README.md)
  4. Wrong file extension (README without .md)
  5. README in subdirectory instead of package root

How to fix "npm WARN publish npm WARN publish No README.md file found"

1Create README.md in package root

Create a new file named exactly README.md in your project's root directory (same level as package.json). This file must use the .md markdown extension.

2Add essential content

At minimum, include:

markdown
# My Package

A useful utility for X.

## Installation

\`\`\`bash
npm install my-package
\`\`\`

## Usage

\`\`\`javascript
const myPackage = require('my-package');
// example code
\`\`\`

## License

MIT
3Include recommended sections

Expand README with:

- Usage - Code examples showing how to use the package
- API - Function/method documentation
- Node/npm requirements - Minimum versions needed
- License - What license the package uses
- Badges - Build status, coverage, version badges (improves quality score)

4Verify .npmignore doesn't exclude README

Check your .npmignore file. Ensure it does NOT contain *.md or explicitly exclude README.md. If present, remove those lines—npm should never ignore README files.

5Test locally before publishing

Run npm pack to create a tarball and verify README.md is included:

bash
npm pack
tar -tzf your-package-name-1.0.0.tgz | grep README

Should show the README file in the output.

Advanced notes

README Content Limits: npm stores only the first 64KB of README content. For large documentation, keep detailed docs in a separate documentation site.

Publishing Workflow: npm REQUIRES a version bump to update the README. Simply editing README.md and re-running npm publish with the same version will not update npmjs.com.

Quality Score Impact: Including a well-structured README with sections, code examples, and badges significantly improves your package's quality score on npmjs.com.

File Format: README.md should be UTF-8 encoded. npm's markdown renderer expects GitHub Flavored Markdown (GFM).

Frequently asked questions

What does "npm WARN publish npm WARN publish No README.md file found" mean?
md file in your package root directory during publication or installation. com page. The registry stores the first 64KB of the README content and renders it as GitHub Flavored Markdown.
How do I fix "npm WARN publish npm WARN publish No README.md file found"?
This warning appears when npm cannot find a README.md file in your package root directory during publication. While not required to publish, npm expects packages to include a README because it serves as the primary documentation displayed on npmjs.com.
What causes "npm WARN publish npm WARN publish No README.md file found"?
No README file in package root directory README in .npmignore or excluded by files field README file has wrong name (README.txt instead of README.md)
Is the "npm WARN publish npm WARN publish No README.md file found" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading