ms - Millisecond Conversion Utility

2.1.3 · active · verified Sun Apr 19

The `ms` package is a small, focused utility designed for converting various time formats to milliseconds and vice versa. It parses human-readable strings (e.g., '2 days', '10h', '5s') into their millisecond equivalents and formats millisecond values back into concise, human-readable strings (e.g., 3600000 becomes '1h'). The current stable version is 2.1.3, though version 3.0.0 is actively in canary, introducing significant changes including full TypeScript support and a transition to an ESM-only distribution. This makes `ms` a reliable, lightweight choice for common duration parsing and formatting tasks in both Node.js and browser environments, distinguished by its minimal API and broad adoption in the Vercel ecosystem.

Common errors

```
TypeError: ms is not a function
```
cause This error often occurs when attempting to call the result of `require('ms')` as a function that itself returns a function, e.g., `require('ms')('1h')()`. The `ms` function is the direct export.

fix Remove the superfluous parentheses: `const ms = require('ms'); ms('1h');` or simply `require('ms')('1h');` for CommonJS. For ESM, ensure `import ms from 'ms';` and then `ms('1h');`.
```
Error: "value" must be a string or a number.
```
cause The `ms()` function received an argument that is neither a string representing a duration nor a number representing milliseconds (e.g., `null`, `undefined`, an object, or an empty string).

fix Ensure the input to `ms()` is always a valid string (e.g., '2 days') or a valid number (e.g., 3600000). Always validate external inputs before passing them to `ms()`.
```
ERR_REQUIRE_ESM
```
cause Attempting to use `require('ms')` in a Node.js CommonJS module when `ms` v3.0.0+ is installed. Version 3.x.x is an ESM-only package and cannot be `require`d directly.

fix Convert your consuming module to ESM by adding `"type": "module"` to your nearest `package.json` file and changing `require('ms')` to `import ms from 'ms';`. Alternatively, for existing CommonJS projects, stick to `ms` v2.x.x.
```
SyntaxError: Cannot use import statement outside a module
```
cause Attempting to use `import ms from 'ms';` in a Node.js file that is treated as a CommonJS module (i.e., it lacks `"type": "module"` in its `package.json` or isn't a `.mjs` file).

fix Add `"type": "module"` to your project's `package.json` file or rename your file to `.mjs`. If maintaining a CommonJS module, you must use `ms` v2.x.x or earlier with `require()`.

Warnings

breaking Version 3.0.0 (currently in canary) introduces a breaking change by transitioning to an ESM-only distribution with full TypeScript support. Projects using CommonJS `require()` will need to migrate to ESM `import` statements or ensure their build pipeline handles ESM modules.
Fix: Migrate from `const ms = require('ms');` to `import ms from 'ms';`. For Node.js, ensure your `package.json` contains `"type": "module"` or use `.mjs` file extensions for your consuming modules.
breaking Version 2.0.0 implemented a security fix limiting string input length to 100 characters to prevent Regular Expression Denial of Service (ReDoS) attacks. Inputs longer than 100 characters will now throw an error, which is a behavioral change from prior versions.
Fix: Ensure that string inputs to `ms()` do not exceed 100 characters. Implement input validation or truncation if processing arbitrary user-provided strings.
gotcha In v2.1.3, the project's repository and internal references were updated from `zeit` to `vercel`. While primarily an internal and branding change, older build systems or direct file references relying on the `zeit` naming convention might require updates.
Fix: Review any explicit references to `zeit/ms` (e.g., in CI configurations, monorepo paths, or dependency mirroring) and update them to `vercel/ms` if necessary. The npm package name remains 'ms'.
gotcha Prior to v2.1.1, `ms` had incomplete or buggy support for negative duration strings (e.g., '-5m'), which could lead to incorrect parsing or unexpected results. This was addressed in v2.1.1 and refined in v2.1.2.
Fix: Update to `ms` version 2.1.1 or later to ensure reliable and correct handling of negative duration strings.

Install

npm install ms npm
yarn add ms yarn
pnpm add ms pnpm

Imports

ms
wrong:
```
const ms = require('ms');
```
correct:
```
import ms from 'ms';
```
For `ms` versions 3.0.0+ (currently in canary), the package is ESM-only. Use `import ms from 'ms';`. For versions 2.x.x and earlier, the package is CommonJS, and `const ms = require('ms');` is the correct import.

Quickstart

Demonstrates basic conversion from human-readable strings to milliseconds and vice versa, including negative durations and the 'long' option.

import ms from 'ms';

// Convert human-readable strings to milliseconds
console.log(`'2 days' -> ${ms('2 days')}ms`);     // 172800000
console.log(`'10h' -> ${ms('10h')}ms`);           // 36000000
console.log(`'1.5h' -> ${ms('1.5h')}ms`);         // 5400000
console.log(`'-30m' -> ${ms('-30m')}ms`);         // -1800000

// Convert milliseconds to human-readable strings
console.log(`3600000ms -> '${ms(3600000)}'`);       // '1h'
console.log(`172800000ms -> '${ms(172800000)}'`);   // '2d'
console.log(`-600000ms -> '${ms(-600000)}'`);     // '-10m'

// Usage with options (e.g., long format)
console.log(`ms(60000, { long: true }) -> '${ms(60000, { long: true })}'`); // '1 minute'

view raw JSON →