Guide · Open source

How to use uuid: generate UUIDs in JavaScript and TypeScript

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

uuid is a JavaScript and TypeScript library from the uuidjs project that creates UUIDs, long identifiers used to tell records, requests or objects apart without a central counter. This guide shows you how to install it, generate the common UUID versions, and check that a string is a valid UUID. It is aimed at developers who need standard-format IDs in browser, Node.js or React Native code.

uuiduuidjs/uuid · ★ 15.3k · MIT Install options & downloads

Quick start

1Install the package. Run npm install uuid in your project folder.
2Import the function you need. Use an ES module import such as import { v4 as uuidv4 } from 'uuid'.
3Generate a UUID. Call uuidv4() to get a random UUID string.
4Pick a version for your needs. Use v4 for random IDs, or v5 when you need the same ID from the same name and namespace.
5Validate incoming IDs. Call validate() on a string to check that it is a valid UUID before using it.

Install uuid from npm

Install the package with npm in your project. The library is installed from npm and works in TypeScript, modern browsers, Node.js and React Native or Expo apps.

Starting with uuid@12, CommonJS is no longer supported, so use ES module imports as shown in the examples.

Prerequisite: Node.js or a bundler that supports npm packages.

npm install uuid

Create your first UUID with v4

The v4 function generates a random (version 4) UUID. Import it by name and call it to get a UUID string back.

Each call returns a new value. The example output in the README is one sample, not a fixed result.

import { v4 as uuidv4 } from 'uuid';

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

Choose the right UUID version

The library supports several RFC 9562 versions. Random v4 is the usual default. Timestamp-based versions (v1, v6, v7) include time information. Name-based versions (v3 and v5) produce the same UUID for the same name and namespace.

The API summary lists v1, v3, v4, v5, v6 and v7. The README marks v8 as intentionally left blank.

v1: timestamp UUID, generated with uuid.v1().
v3: name-based UUID using MD5. The README notes that per the RFC, SHA-1 (v5) is preferred if backward compatibility is not an issue.
v4: random UUID, generated with uuid.v4().
v5: name-based UUID using SHA-1, generated with uuid.v5(name, namespace).
v6: timestamp UUID with reordered fields, generated with uuid.v6(). You can convert v1 to v6 with v1ToV6 and back with v6ToV1.
v7: Unix Epoch time-based UUID, generated with uuid.v7().

Generate a name-based UUID with v5

Name-based UUIDs need a name and a namespace UUID. The README lists the v5 signature as name, namespace, with optional buffer and offset arguments. The namespace can be a string or an array of 16 bytes.

Use the same name and namespace to get the same UUID again, which is useful when you need a repeatable ID for a given input.

Validate and inspect UUID strings

Use validate to test whether a string is a valid UUID. Use version to detect which RFC version a UUID uses. The README describes validate as testing a string, and version as detecting the RFC version.

Use parse to turn a UUID string into 16 bytes, and stringify to turn bytes back into a string. parse throws a TypeError if the input is not a valid UUID.

NIL is the all-zeros UUID and MAX is the all-ones UUID.
stringify throws a TypeError if a valid UUID string cannot be generated.

import { validate, version, NIL } from 'uuid';

validate(NIL); // check a string
version(NIL);  // detect the RFC version

Use the command line and check your setup

The README lists a uuid command line utility as one of the project's features. The source excerpt does not show its usage, so check the README for the exact commands before relying on it.

The README also says the library works in Chrome, Safari, Firefox, Edge, NodeJS, TypeScript and React Native / Expo.

The v1 and v7 functions can throw an Error if more than 10M UUIDs per second are requested.

What people use it for

Giving records in a front-end app a unique ID before they are saved to a server.
Creating request or correlation IDs in Node.js back-end code.
Generating stable IDs from a known name and namespace with v5.
Creating IDs in React Native or Expo apps.

Frequently asked questions

Is uuid free to use?

The package is released under the MIT licence, according to the project's summary. The MIT licence generally allows free use, but check the licence file in the repository for the full terms.

How do I install uuid?

Run npm install uuid in your project. You need Node.js or a bundler that supports npm packages.

Is a UUID secure enough for passwords or keys?

No. A UUID is an identifier, not a secret, and the README does not present it as cryptographic key material. Use a proper cryptographic tool for secrets.

Can uuid generate IDs for a database sequence?

Not really. The library only generates IDs in code. If you need a database-generated sequence, use the database's own ID feature instead.

Does uuid work with TypeScript?

Yes. The README lists TypeScript as a supported platform and the project itself is written in TypeScript.

What are alternatives to uuid?

The project's comparable projects are nanoid, crypto.randomUUID and ulid. Each has different output formats, so pick based on whether you need the standard UUID format.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use uuid if you are a JavaScript or TypeScript developer who needs standard RFC-format IDs in browsers, Node.js or React Native. Pick something else if you need a database-generated sequence, cryptographic key material, or you work outside JavaScript.

Install options & downloads