| name | npm-downloads |
| description | Get download statistics for an npm package over time. Use when the user asks for package download counts, popularity metrics, or usage statistics. |
Get npm Download Statistics
Retrieve download statistics for an npm package over a specified time period.
Usage
npx tsx scripts/downloads.ts <package-name> [options]
Arguments
| Argument | Required | Description |
|---|
package-name | Yes | The exact package name (case-sensitive) |
Options
| Option | Description |
|---|
--period=PERIOD | Time period: last-week, last-month, last-year (default: last-month) |
--no-cache | Bypass cache and fetch fresh data from API |
Output
Downloads for react (last-month)
--------------------------------
Period: 2023-10-01 to 2023-10-31 (31 days)
Total downloads: 15,234,567
Average per day: 491,438
Peak day: 2023-10-15 (678,234 downloads)
Script Execution (Preferred)
npx tsx scripts/downloads.ts <package-name> [options]
Options:
--period=PERIOD - Time period: last-week, last-month, last-year (default: last-month)--no-cache - Bypass cache and fetch fresh data from API
Run from the npm-registry plugin directory: ~/.claude/plugins/cache/npm-registry/
Downloads API
GET https://api.npmjs.org/downloads/range/{period}:{package}
Parameters
| Parameter | Required | Description |
|---|
period | Yes | Time period: last-week, last-month, last-year, or date range (YYYY-MM-DD:YYYY-MM-DD) |
package | Yes | The exact package name (case-sensitive) |
Examples
Last week:
https://api.npmjs.org/downloads/range/last-week:react
Last month:
https://api.npmjs.org/downloads/range/last-month:react
Last year:
https://api.npmjs.org/downloads/range/last-year:react
Custom date range:
https://api.npmjs.org/downloads/range/2023-01-01:2023-12-31:react
Response Format
{
"downloads": [
{
"downloads": 1234567,
"day": "2023-10-01"
}
],
"start": "2023-10-01",
"end": "2023-10-31",
"package": "react"
}
| last-month | Past 30 days |
| last-year | Past 365 days |
| YYYY-MM-DD:YYYY-MM-DD | Custom date range |
Custom date ranges must be in ISO 8601 format (YYYY-MM-DD).
Download Trends
The data can show:
- Weekly patterns - Higher weekday downloads for development tools
- Release spikes - Sudden increases after major version releases
- Seasonal trends - Patterns based on project cycles
- Long-term growth - Overall adoption trends
Caching
Download statistics are cached for 24 hours. Historical download data doesn't change, so the cache provides the same data with better performance.
Use the --no-cache flag to bypass the cache.
Related
- Use
npm-info to get package metadata alongside download stats
- Use
npm-search to discover packages with high download counts
- Use NPMS.io for quality scores alongside download metrics
Error Handling
Package not found: Download stats are only available for published packages. Use npm-exists to verify the package exists first.
Invalid period: Ensure the period format is correct. Date ranges must use colons to separate dates from the package name.
No data: Very new packages may not have download statistics yet. Statistics are typically available within 24-48 hours of first publish.
Data Limitations
- Delay: Download counts are typically 24-48 hours behind
- Granularity: Data is available per day, not per hour
- Scope: Counts include all download sources (npm install, CDN, mirrors)
- Accuracy: Numbers are approximate and may include failed downloads
