uuid Documentation

File: README.md Copy Chapter

uuid [](https://github.com/uuidjs/uuid/actions?query=workflow%3ACI) [](https://github.com/uuidjs/uuid/actions/workflows/browser.yml)

For the creation of RFC9562 (formerly RFC4122) UUIDs

• Complete - Support for all RFC9562 UUID versions
• Cross-platform - Support for...
  • Typescript
  • Chrome, Safari, Firefox, and Edge
  • NodeJS
  • React Native / Expo
• Secure - Uses modern crypto API for random values
• Compact - Zero-dependency, tree-shakable
• CLI - uuid command line utility

[!NOTE]

Starting with uuid@12 CommonJS is no longer supported. See implications and motivation for details.

Quickstart Copy Chapter

1. Install

npm install uuid

2. Create a UUID

import { v4 as uuidv4 } from 'uuid';

uuidv4(); // ⇨ 'b18794e8-5d0d-417c-b361-ba38e78411b4'

For timestamp UUIDs, namespace UUIDs, and other options read on ...

API Summary Copy Chapter

API Copy Chapter

uuid.NIL Copy Section

The nil UUID string (all zeros).

Example:

import { NIL as NIL_UUID } from 'uuid';

NIL_UUID; // ⇨ '00000000-0000-0000-0000-000000000000'

uuid.MAX Copy Section

The max UUID string (all ones).

Example:

import { MAX as MAX_UUID } from 'uuid';

MAX_UUID; // ⇨ 'ffffffff-ffff-ffff-ffff-ffffffffffff'

uuid.parse(str) Copy Section

Convert UUID string to array of bytes

[!NOTE]
Ordering of values in the byte arrays used by parse() and stringify() follows the left ↠ right order of hex-pairs in UUID strings. As shown in the example below.

Example:

import { parse as uuidParse } from 'uuid';

// Parse a UUID
uuidParse('6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'); // ⇨
// Uint8Array(16) [
//   110, 192, 189, 127,  17,
//   192,  67, 218, 151,  94,
//    42, 138, 217, 235, 174,
//    11
// ]

uuid.stringify(arr[, offset]) Copy Section

Convert array of bytes to UUID string

[!NOTE]
Ordering of values in the byte arrays used by parse() and stringify() follows the left ↠ right order of hex-pairs in UUID strings. As shown in the example below.

Example:

import { stringify as uuidStringify } from 'uuid';

const uuidBytes = Uint8Array.of(
  0x6e,
  0xc0,
  0xbd,
  0x7f,
  0x11,
  0xc0,
  0x43,
  0xda,
  0x97,
  0x5e,
  0x2a,
  0x8a,
  0xd9,
  0xeb,
  0xae,
  0x0b
);

uuidStringify(uuidBytes); // ⇨ '6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'

uuid.v1([options[, buffer[, offset]]]) Copy Section

Create an RFC version 1 (timestamp) UUID

Example:

import { v1 as uuidv1 } from 'uuid';

uuidv1(); // ⇨ '57fd0000-c7d3-11ef-841d-514d2167fc5b'

Example using options:

import { v1 as uuidv1 } from 'uuid';

const options = {
  node: Uint8Array.of(0x01, 0x23, 0x45, 0x67, 0x89, 0xab),
  clockseq: 0x1234,
  msecs: new Date('2011-11-01').getTime(),
  nsecs: 5678,
};
uuidv1(options); // ⇨ '710b962e-041c-11e1-9234-0123456789ab'

uuid.v1ToV6(uuid) Copy Section

Convert a UUID from version 1 to version 6

import { v1ToV6 } from 'uuid';

v1ToV6('92f62d9e-22c4-11ef-97e9-325096b39f47'); // ⇨ '1ef22c49-2f62-6d9e-97e9-325096b39f47'

uuid.v3(name, namespace[, buffer[, offset]]) Copy Section

Create an RFC version 3 (namespace w/ MD5) UUID

API is identical to v5(), but uses "v3" instead.

[!IMPORTANT]
Per the RFC, "If backward compatibility is not an issue, SHA-1 [Version 5] is preferred."

uuid.v4([options[, buffer[, offset]]]) Copy Section

Create an RFC version 4 (random) UUID

Example:

import { v4 as uuidv4 } from 'uuid';

uuidv4(); // ⇨ 'b18794e8-5d0d-417c-b361-ba38e78411b4'

Example using predefined random values:

import { v4 as uuidv4 } from 'uuid';

const v4options = {
  random: Uint8Array.of(
    0x10,
    0x91,
    0x56,
    0xbe,
    0xc4,
    0xfb,
    0xc1,
    0xea,
    0x71,
    0xb4,
    0xef,
    0xe1,
    0x67,
    0x1c,
    0x58,
    0x36
  ),
};
uuidv4(v4options); // ⇨ '109156be-c4fb-41ea-b1b4-efe1671c5836'

uuid.v5(name, namespace[, buffer[, offset]]) Copy Section

Create an RFC version 5 (namespace w/ SHA-1) UUID

[!NOTE]
The RFC DNS and URL namespaces are available as v5.DNS and v5.URL.

Example with custom namespace:

import { v5 as uuidv5 } from 'uuid';

// Define a custom namespace.  Readers, create your own using something like
// https://www.uuidgenerator.net/
const MY_NAMESPACE = '1b671a64-40d5-491e-99b0-da01ff1f3341';

uuidv5('Hello, World!', MY_NAMESPACE); // ⇨ '630eb68f-e0fa-5ecc-887a-7c7a62614681'

Example with RFC URL namespace:

import { v5 as uuidv5 } from 'uuid';

uuidv5('https://www.w3.org/', uuidv5.URL); // ⇨ 'c106a26a-21bb-5538-8bf2-57095d1976c1'

uuid.v6([options[, buffer[, offset]]]) Copy Section

Create an RFC version 6 (timestamp, reordered) UUID

This method takes the same arguments as uuid.v1().

import { v6 as uuidv6 } from 'uuid';

uuidv6(); // ⇨ '1efc7d35-7fd0-6000-841d-504d2167fc5b'

Example using options:

import { v6 as uuidv6 } from 'uuid';

const options = {
  node: [0x01, 0x23, 0x45, 0x67, 0x89, 0xab],
  clockseq: 0x1234,
  msecs: new Date('2011-11-01').getTime(),
  nsecs: 5678,
};
uuidv6(options); // ⇨ '1e1041c7-10b9-662e-9234-0123456789ab'

uuid.v6ToV1(uuid) Copy Section

Convert a UUID from version 6 to version 1

import { v6ToV1 } from 'uuid';

v6ToV1('1ef22c49-2f62-6d9e-97e9-325096b39f47'); // ⇨ '92f62d9e-22c4-11ef-97e9-325096b39f47'

uuid.v7([options[, buffer[, offset]]]) Copy Section

Create an RFC version 7 (random) UUID

Example:

import { v7 as uuidv7 } from 'uuid';

uuidv7(); // ⇨ '01941f29-7c00-73e4-a310-744d2167fc5b'

~~uuid.v8()~~ Copy Section

"Intentionally left blank"

[!NOTE]
Version 8 (experimental) UUIDs are "for experimental or vendor-specific use cases". The RFC does not define a creation algorithm for them, which is why this package does not offer a v8() method. The validate() and version() methods do work with such UUIDs, however.

uuid.validate(str) Copy Section

Test a string to see if it is a valid UUID

Example:

import { validate as uuidValidate } from 'uuid';

uuidValidate('not a UUID'); // ⇨ false
uuidValidate('6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'); // ⇨ true

Using validate and version together it is possible to do per-version validation, e.g. validate for only v4 UUIds.

import { version as uuidVersion } from 'uuid';
import { validate as uuidValidate } from 'uuid';

function uuidValidateV4(uuid) {
  return uuidValidate(uuid) && uuidVersion(uuid) === 4;
}

const v1Uuid = 'd9428888-122b-11e1-b85c-61cd3cbb3210';
const v4Uuid = '109156be-c4fb-41ea-b1b4-efe1671c5836';

uuidValidateV4(v4Uuid); // ⇨ true
uuidValidateV4(v1Uuid); // ⇨ false

uuid.version(str) Copy Section

Detect RFC version of a UUID

Example:

import { version as uuidVersion } from 'uuid';

uuidVersion('45637ec4-c85f-11ea-87d0-0242ac130003'); // ⇨ 1
uuidVersion('6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'); // ⇨ 4

[!NOTE]
This method returns 0 for the NIL UUID, and 15 for the MAX UUID.

Command Line Copy Chapter

UUIDs can be generated from the command line using uuid.

$ npx uuid
ddeb27fb-d9a0-4624-be4d-4615062daed4

The default is to generate version 4 UUIDS, however the other versions are supported. Type uuid --help for details:

$ npx uuid --help

Usage:
  uuid
  uuid v1
  uuid v3 <name> <namespace uuid>
  uuid v4
  uuid v5 <name> <namespace uuid>
  uuid v7
  uuid --help

Note: <namespace uuid> may be "URL" or "DNS" to use the corresponding UUIDs
defined by RFC9562

`options` Handling for Timestamp UUIDs Copy Chapter

Prior to uuid@11, it was possible for options state to interfere with the internal state used to ensure uniqueness of timestamp-based UUIDs (the v1(), v6(), and v7() methods). Starting with uuid@11, this issue has been addressed by using the presence of the options argument as a flag to select between two possible behaviors:

• Without options: Internal state is utilized to improve UUID uniqueness.
• With options: Internal state is NOT used and, instead, appropriate defaults are applied as needed.

Support Copy Chapter

Browsers: uuid builds are tested against the latest version of desktop Chrome, Safari, Firefox, and Edge. Mobile versions of these same browsers are expected to work but aren't currently tested.

Node: uuid builds are tested against node (LTS releases), plus one prior. E.g. At the time of this writing node@20 is the "maintenance" release and node@24 is the "current" release, so uuid supports node@20-node@24.

Typescript: TS versions released within the past two years are supported. source

Known issues Copy Chapter

"getRandomValues() not supported" Copy Section

This error occurs in environments where the standard crypto.getRandomValues() API is not supported. This issue can be resolved by adding an appropriate polyfill:

React Native / Expo

1. Install react-native-get-random-values
2. Import it before uuid. Since uuid might also appear as a transitive dependency of some other imports it's safest to just import react-native-get-random-values as the very first thing in your entry point:

import 'react-native-get-random-values';
import { v4 as uuidv4 } from 'uuid';

Generated from README_js.md by runmd

File: examples/typescript/README.md Copy Chapter

uuid test for typescript support (not really an example)

npm install
npm test

This runs tsc using the oldest version of TypeScript supported by this project

File: examples/node-webpack/README.md Copy Chapter

uuid example Node.js with Webpack

npm install
npm test

This will run webpack and execute the resulting bundles in ./dist.

File: examples/browser-webpack/README.md Copy Chapter

uuid example Browser with Webpack

npm install
npm start

Then navigate to example-*.html.

The example-v{1,4}.js demonstrate that treeshaking works as expected (webpack output below):

Asset      Size  Chunks             Chunk Names
all.js  8.54 KiB       0  [emitted]  all
 v1.js   2.6 KiB       1  [emitted]  v1
 v4.js     2 KiB       2  [emitted]  v4

File: examples/browser-rollup/README.md Copy Chapter

uuid example Browser with rollup.js

npm install
npm start

Then navigate to example-*.html.

The example-v{1,4,7}.js demonstrate that treeshaking works as expected:

$ du -sh dist/*
 20K  dist/all.js
8.0K  dist/v1.js
4.0K  dist/v4.js
4.0K  dist/v7.js

File: examples/browser-esmodules/README.md Copy Chapter

uuid example Browser with native ECMAScript Modules

npm install
npm start

Then navigate to example.html.

File: examples/benchmark/README.md Copy Chapter

uuid Benchmark

npm install

Node.js Copy Chapter

To run the benchmark in Node.js, run npm test.

Browser Copy Chapter

To run the benchmark in the browser run npm run start, open benchmark.html, and check the console.

Example output ([email protected], MacBook Pro (Retina, 13-inch, Early 2015), 3.1 GHz Dual-Core Intel Core i7):

Starting. Tests take ~1 minute to run ...
uuidv1() x 1,306,861 ops/sec ±2.62% (85 runs sampled)
uuidv1() fill existing array x 4,750,515 ops/sec ±2.76% (88 runs sampled)
uuidv4() x 302,174 ops/sec ±3.06% (81 runs sampled)
uuidv4() fill existing array x 359,703 ops/sec ±3.67% (82 runs sampled)
uuidv3() x 105,667 ops/sec ±3.84% (79 runs sampled)
uuidv5() x 110,886 ops/sec ±2.55% (81 runs sampled)
Fastest is uuidv1() fill existing array