Getting Started

This page covers the installation, import, and basic usage of the ms package for converting time formats to milliseconds and formatting milliseconds back to human-readable strings.

Prerequisites

• Node.js version 20 or later (as specified in package.json). The project is tested against Node.js versions 20, 22, and 24 .github/workflows/test.yml:10-13.
• A package manager: npm, yarn, pnpm, deno, or bun.

Installation

Install ms using your preferred package manager:

npm install ms
yarn add ms
pnpm add ms
deno add npm:ms
bun add ms

Importing ms

Default Import (Recommended)

The package exports a single default function that can parse time strings or format millisecond values:

import ms from 'ms';

Named Imports

As of version 3.0, you can also import the individual helper functions parse, format, and parseStrict:

import { parse, format, parseStrict } from 'ms';

For TypeScript projects, you may also import the StringValue type to enforce type-safe string arguments:

import { ms, type StringValue } from 'ms';

Basic Usage

Parsing a Time String to Milliseconds

The simplest way to convert a time string to milliseconds is to call ms with a string argument:

ms('2 days') // 172800000
ms('1d') // 86400000
ms('10h') // 36000000
ms('2.5 hrs') // 9000000
ms('2h') // 7200000
ms('1m') // 60000
ms('5s') // 5000
ms('1y') // 31557600000
ms('100') // 100
ms('-3 days') // -259200000
ms('-1h') // -3600000
ms('-200') // -200

If no unit is provided (e.g., '100'), the value is treated as milliseconds. Fractional values like '0.5m', '-0.5m', '.5m', and '-.5m' are also supported.

Formatting Milliseconds to a String

To convert a millisecond value back to a human-readable string, pass a number to ms:

ms(60000) // "1m"
ms(2 * 60000) // "2m"
ms(-3 * 60000) // "-3m"
ms(ms('10 hours')) // "10h"

Long-Form Output

Pass { long: true } as the second argument to get full unit names:

ms(60000, { long: true }) // "1 minute"
ms(2 * 60000, { long: true }) // "2 minutes"
ms(-3 * 60000, { long: true }) // "-3 minutes"
ms(ms('10 hours'), { long: true }) // "10 hours"

Using the Helper Functions

The parse and format functions provide the same behavior as the default ms function but are available as named exports for clarity:

import { parse, format } from 'ms';

parse('1h'); // 3600000
format(2000); // "2s"

Type Safety with parseStrict

For strict type checking at compile time, use parseStrict. It accepts only string literals that match the expected time format and will cause a TypeScript compilation error if a generic string is passed:

import { parseStrict } from 'ms';

parseStrict('1h'); // 3600000

function example(s: string) {
 return parseStrict(s); // TypeScript error: Argument of type 'string' is not assignable to parameter of type 'StringValue'
}

Edge Runtime Compatibility

ms is compatible with the Edge Runtime and can be used in environments like Vercel Edge Functions. The following example demonstrates usage in a Next.js edge API route:

import { ms } from 'ms';
const start = Date.now();

export default (req) => {
 return new Response(`Alive since ${ms(Date.now() - start)}`);
};

export const config = {
 runtime: 'experimental-edge',
};

Verifying Installation

To verify that ms is installed and working correctly, run the project's test suite:

pnpm test

This executes all test scripts defined in package.json, including test:nodejs and test:edge. The CI workflow runs these tests against Node.js versions 20, 22, and 24 .github/workflows/test.yml:10-13.

Supported Input Formats

The following unit formats are recognized (case-insensitive, with or without a space between the number and unit):

Related Pages

• Overview
• Architecture