uuid

What is uuid?

The uuid npm package is used to generate universally unique identifiers (UUIDs), which are 128-bit numbers used to uniquely identify information in computer systems. The package supports multiple versions of UUIDs, each with different methods of generation based on requirements such as randomness, time-based generation, and name-based generation using namespaces.

What are uuid's main functionalities?

Generate UUID v1

Generates a version 1 UUID based on timestamp and MAC address of the host machine, ensuring temporal uniqueness.

const { v1: uuidv1 } = require('uuid');
console.log(uuidv1());

Generate UUID v4

Generates a version 4 UUID using random or pseudo-random numbers, providing a higher degree of randomness.

const { v4: uuidv4 } = require('uuid');
console.log(uuidv4());

Generate UUID v3

Generates a version 3 UUID using MD5 hashing of a namespace identifier and a name.

const { v3: uuidv3 } = require('uuid');
const MY_NAMESPACE = '1b671a64-40d5-491e-99b0-da01ff1f3341';
console.log(uuidv3('Hello, World!', MY_NAMESPACE));

Generate UUID v5

Generates a version 5 UUID using SHA-1 hashing of a namespace identifier and a name, providing better uniqueness and lower collision probability than v3.

const { v5: uuidv5 } = require('uuid');
const MY_NAMESPACE = '1b671a64-40d5-491e-99b0-da01ff1f3341';
console.log(uuidv5('Hello, World!', MY_NAMESPACE));

Other packages similar to uuid

shortid

ShortId generates short, non-sequential, URL-friendly unique ids. Unlike uuid, which generates 128-bit long UUIDs, ShortId creates shorter ids, which can be easier to use in URLs or when space is limited. However, ShortId is not recommended for security-critical applications due to the shorter identifier length and lower entropy.

nanoid

NanoId is a tiny, secure, URL-friendly, unique string ID generator for JavaScript. It is similar to uuid v4 in that it provides a way to generate random IDs, but it offers a customizable alphabet and length, allowing for a wider range of possible IDs. NanoId claims to be faster and more compact than UUID, making it a good alternative for many applications.

cuid

CUID (Collision-resistant Unique Identifier) is another alternative for generating unique identifiers. It is designed to be more collision-resistant than uuid and is optimized for horizontal scaling and sequential lookup performance. CUIDs are longer than UUIDs and contain a timestamp, which can be useful for sorting records in a database.

README

uuid

For the creation of RFC9562 (formally RFC4122) UUIDs

• Complete - Support for all RFC9562 UUID versions
• Cross-platform - Support for ...
  • CommonJS, ECMAScript Modules
  • NodeJS 16+ (LTS releases)
  • Chrome, Safari, Firefox, Edge browsers
  • React Native / Expo
• Secure - Cryptographically-strong random values
• Compact - No dependencies, tree-shakable
• CLI - Includes the uuid command line utility
• Typescript - Types now included

[!NOTE] w> uuid@11 is now available: See the CHANGELOG for details. TL;DR:

• TypeScript support is now included (remove @types/uuid from your dependencies)
• Subtle changes to how the options arg is interpreted for v1(), v6(), and v7(). See details
• Binary UUIDs are now Uint8Arrays. (May impact callers of parse(), stringify(), or that pass an option#buf argument to v1()-v7().)

Quickstart

1. Install

npm install uuid

2. Create a UUID

ESM-syntax (must use named exports):

import { v4 as uuidv4 } from 'uuid';
uuidv4(); // ⇨ '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'

... CommonJS:

const { v4: uuidv4 } = require('uuid');
uuidv4(); // ⇨ '1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed'

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

API Summary

uuid.NIL	The nil UUID string (all zeros)	New in uuid@8.3
uuid.MAX	The max UUID string (all ones)	New in uuid@9.1
uuid.parse()	Convert UUID string to array of bytes	New in uuid@8.3
uuid.stringify()	Convert array of bytes to UUID string	New in uuid@8.3
uuid.v1()	Create a version 1 (timestamp) UUID
uuid.v1ToV6()	Create a version 6 UUID from a version 1 UUID	New in uuid@10
uuid.v3()	Create a version 3 (namespace w/ MD5) UUID
uuid.v4()	Create a version 4 (random) UUID
uuid.v5()	Create a version 5 (namespace w/ SHA-1) UUID
uuid.v6()	Create a version 6 (timestamp, reordered) UUID	New in uuid@10
uuid.v6ToV1()	Create a version 1 UUID from a version 6 UUID	New in uuid@10
uuid.v7()	Create a version 7 (Unix Epoch time-based) UUID	New in uuid@10
uuid.v8()	"Intentionally left blank"
uuid.validate()	Test a string to see if it is a valid UUID	New in uuid@8.3
uuid.version()	Detect RFC version of a UUID	New in uuid@8.3

API

uuid.NIL

The nil UUID string (all zeros).

Example:

import { NIL as NIL_UUID } from 'uuid';

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

uuid.MAX

The max UUID string (all ones).

Example:

import { MAX as MAX_UUID } from 'uuid';

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

uuid.parse(str)

Convert UUID string to array of bytes

str	A valid UUID String
returns	Uint8Array[16]
throws	TypeError if str is not a valid UUID

[!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])

Convert array of bytes to UUID string

arr	Array-like collection of 16 values (starting from offset) between 0-255.
[offset = 0]	Number Starting index in the Array
returns	String
throws	TypeError if a valid UUID string cannot be generated

[!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]]])

Create an RFC version 1 (timestamp) UUID

[options]	Object with one or more of the following properties:
[options.node = (random) ]	RFC "node" field as an Array[6] of byte values (per 4.1.6)
[options.clockseq = (random)]	RFC "clock sequence" as a Number between 0 - 0x3fff
[options.msecs = (current time)]	RFC "timestamp" field (Number of milliseconds, unix epoch)
[options.nsecs = 0]	RFC "timestamp" field (Number of nanoseconds to add to msecs, should be 0-10,000)
[options.random = (random)]	Array of 16 random bytes (0-255) used to generate other fields, above
[options.rng]	Alternative to options.random, a Function that returns an Array of 16 random bytes (0-255)
[buffer]	Array | Buffer If specified, uuid will be written here in byte-form, starting at offset
[offset = 0]	Number Index to start writing UUID bytes in buffer
returns	UUID String if no buffer is specified, otherwise returns buffer
throws	Error if more than 10M UUIDs/sec are requested

[!NOTE] The default node id (the last 12 digits in the UUID) is generated once, randomly, on process startup, and then remains unchanged for the duration of the process.

[!NOTE] options.random and options.rng are only meaningful on the very first call to v1(), where they may be passed to initialize the internal node and clockseq fields.

Example:

import { v1 as uuidv1 } from 'uuid';

uuidv1(); // ⇨ '2c5ea4c0-4067-11e9-9bdd-2b0d7b3dcb6d'

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)

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]])

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]]])

Create an RFC version 4 (random) UUID

[options]	Object with one or more of the following properties:
[options.random]	Array of 16 random bytes (0-255)
[options.rng]	Alternative to options.random, a Function that returns an Array of 16 random bytes (0-255)
[buffer]	Array | Buffer If specified, uuid will be written here in byte-form, starting at offset
[offset = 0]	Number Index to start writing UUID bytes in buffer
returns	UUID String if no buffer is specified, otherwise returns buffer

Example:

import { v4 as uuidv4 } from 'uuid';

uuidv4(); // ⇨ '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'

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]])

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

name	String | Array
namespace	String | Array[16] Namespace UUID
[buffer]	Array | Buffer If specified, uuid will be written here in byte-form, starting at offset
[offset = 0]	Number Index to start writing UUID bytes in buffer
returns	UUID String if no buffer is specified, otherwise returns buffer

[!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]]])

Create an RFC version 6 (timestamp, reordered) UUID

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

import { v6 as uuidv6 } from 'uuid';

uuidv6(); // ⇨ '1e940672-c5ea-64c0-9b5d-ab8dfbbd4bed'

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)

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]]])

Create an RFC version 7 (random) UUID

[options]	Object with one or more of the following properties:
[options.msecs = (current time)]	RFC "timestamp" field (Number of milliseconds, unix epoch)
[options.random = (random)]	Array of 16 random bytes (0-255) used to generate other fields, above
[options.rng]	Alternative to options.random, a Function that returns an Array of 16 random bytes (0-255)
[options.seq = (random)]	32-bit sequence Number between 0 - 0xffffffff. This may be provided to help insure uniqueness for UUIDs generated within the same millisecond time interval. Default = random value.
[buffer]	Array | Buffer If specified, uuid will be written here in byte-form, starting at offset
[offset = 0]	Number Index to start writing UUID bytes in buffer
returns	UUID String if no buffer is specified, otherwise returns buffer

Example:

import { v7 as uuidv7 } from 'uuid';

uuidv7(); // ⇨ '01695553-c90c-705a-b56d-778dfbbd4bed'

uuid.v8()

"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)

Test a string to see if it is a valid UUID

str	String to validate
returns	true if string is a valid UUID, false otherwise

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)

Detect RFC version of a UUID

str	A valid UUID String
returns	Number The RFC version of the UUID
throws	TypeError if str is not a valid 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

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

Prior to uuid@11, it was possible for options state to interfere with the internal state used to insure 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.

Known issues

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';

---

Markdown generated from README_js.md by

Changelog

11.0.3 (2024-11-04)

Bug Fixes

• apply stricter typing to the v* signatures (#831) (c2d3fed)
• export internal uuid types (#833) (341edf4)
• remove sourcemaps (#827) (b93ea10)
• revert "simplify type for v3 and v5" (#835) (e2dee69)