Nutrient Packed Morsels

    TypeScript icon, indicating that this package has built-in type declarations

    4.5.0 • Public • Published


    The smallest & fastest library for really easy, totally type-safe unit conversions in TypeScript & JavaScript.

    published npm version test coverage bundle size npm monthly downloads type definitions license CI

    npm install convert
    # or
    yarn add convert

    More installation examples below, including browser builds.

    convert(5, 'miles').to('km');
    convertMany('4d 16h').to('minutes');


    • Full build time and runtime validation of conversions
    • Using a web framework like Next.js or Nuxt.js? You get 0-cost build-time conversions. Convert is totally side-effect free, so conversions will be precalculated at build-time, so absolutely zero conversion code is sent to clients!
    • Works in browsers and Node.js (UMD and ESM builds will work anywhere)
    • Out of the box ES3 backwards-compatibility (CI tests on Node.js v0.9.1)
    • Absolutely tiny bundle size and 0 dependencies
    • Supports bigints without breaking on old engines


    Generated API documentation for the latest version is available online.

    View docs.

    // ESM:
    import convert from 'convert';
    // CJS:
    const {convert} = require('convert');
    // 360 seconds into minutes
    convert(360, 'seconds').to('minutes');
    // -> 6
    // BigInt support
    convert(20n, 'hours').to('minutes');
    // -> 1200n
    // Format to the best unit automatically
    convert(5500, 'meters').to('best');
    // -> { quantity: 5.5, unit: 'km', toString: () => '5.5km' }
    // We also do length, data, volume, mass, temperature, and more
    convert(5, 'kilometers').to('nautical miles');
    convert(12, 'pounds').to('ounces');
    convert(8192, 'bytes').to('KiB');
    convert(10, 'atmospheres').to('kPa');
    convert(451, 'fahrenheit').to('celsius');

    Converting many units

    import {convertMany} from 'convert';
    const {convertMany} = require('convert');
    // Convert 1 day and 8 hours into ms

    Converting to best unit

    import convert from 'convert';
    const {convert} = require('convert');
    // Convert into the best unit
    const duration = convert(36, 'h').to('best');
    // -> { quantity: 1.5, unit: 'd', toString: () => '1.5d' }
    // The toString() method means you can automatically cast the object to a string without any issues
    'duration is ' + duration;
    // -> duration is 1.5d
    // You can also specify to use a specific kind of units (metric or imperial, metric is default)
    convert(3.5, 'km').to('best'); // -> { quantity: 3.5, unit: 'km', toString: () => '3.5km' }
    convert(3.5, 'km').to('best', 'metric'); // -> { quantity: 3.5, unit: 'km', toString: () => '3.5km' }
    convert(3.5, 'km').to('best', 'imperial'); // -> { quantity: 2.17, unit: 'mi', toString: () => '3.5mi' }

    ms shorthand

    import {ms} from 'convert';
    const {ms} = require('convert');
    // Convert a duration into milliseconds
    ms('1d 2h 30min');
    // -> 95400000
    // Convert milliseconds to a string
    // -> '1d'


    Package manager

    Convert is published as convert on npm.

    npm install convert
    # or
    yarn add convert


    // This chooses which build to use depending on NODE_ENV
    const {convert} = require('convert');
    // You can also specify which build to use
    const {convert} = require('convert/dev');
    const {convert} = require('convert/prod');

    ES Modules

    // The production build is the default
    import convert from 'convert';
    // ESM does not have automatic build switching, you must explicitly import the dev build
    import convert from 'convert/dev';
    import convert from 'convert/prod';


    Pick your favorite CDN:


    <script type="module">
    	import convert from '';
    	import convert from '';
    	import convert from '';
    	import convert from '';

    UMD (global)

    <script src=""></script>
    <script src=""></script>


    Convert is better than other unit conversion libraries because it's faster and smaller than them, while having the same features. Benchmarks of popular unit conversion libraries, including Convert are available here.

    Convert is the fastest, taking less than a microsecond for all functions. That's a little over 3 million convert() calls per second.

    Bundle size comparison

    npm bundle size of convert

    npm bundle size of safe-units

    npm bundle size of convert-units

    npm bundle size of js-quantities

    npm bundle size of uom + npm bundle size of uom-units


    npm i convert

    DownloadsWeekly Downloads






    Unpacked Size

    932 kB

    Total Files


    Last publish


    • jonahsnider