uuid review
uuid implements RFC 9562 identifiers in JavaScript. It generates random v4, time-based v1, reordered time-based v6, Unix-time v7, and deterministic namespace v3 or v5 values; it also validates strings, reports versions, converts to and from bytes, converts v1 and v6 layouts, and exposes NIL and MAX sentinels. Version 14.0.2 fixes nanosecond overflow and random-node multicast handling in v1 plus the default sequence formula used by the lower-level v7 byte generator. Our Node 22 install loaded the ESM package through both import and require(), included TypeScript declarations, and built for browsers without another dependency.
Use uuid for v7 database identifiers, v5 namespace derivation, or interoperability that requires RFC 9562. For random v4 alone, the platform API removes a dependency and is easier to justify.
We installed it
| Install | ✓ · 0.4s | 1 package on disk · 1 MB |
| Import | ✓ | ESM import works · require() works · ESM package with exports map |
| Browser | 3.8 KB | gzipped (10 KB minified), bundled with esbuild |
| Types | ✓ | TypeScript types bundled |
| Known vulns | 0 | 0 critical · 0 high · 0 moderate · 0 low (npm audit) |
Answers from our run
Does uuid install cleanly?
Yes. In a fresh container with an empty cache, npm install uuid finished in 0.4s, leaving 1 package and 1 MB on disk. npm audit reported no known vulnerabilities.
How much does uuid add to a browser bundle?
3.8 KB gzipped (10 KB minified) when the whole package is bundled for the browser with esbuild. Importing only part of it is usually smaller.
Does uuid work with both ESM and CommonJS?
Yes. Both import 'uuid' and require('uuid') worked in Node 22 in our run. The package is published as ESM with an exports map.
Does uuid include TypeScript types?
Yes, type declarations ship inside the package, so no @types install is needed.
uuid or nanoid: which should you use?
nanoid: Use it when compact URL-friendly random strings matter and no external system requires UUID format. Use uuid for v7 database identifiers, v5 namespace derivation, or interoperability that requires RFC 9562.
When should you not use uuid?
You only call v4 on current Node or browsers; crypto.randomUUID() provides the standard random UUID with no package
Use it if
- A database or external API requires RFC UUID text and you need more than the platform's random v4 generator
- New database keys should use UUID v7 for time order while keeping a standard UUID column and wire format
- The same namespace and name must always produce the same identifier through v5
- Code needs version checks, validation, byte conversion, NIL or MAX constants, or v1-to-v6 conversion around existing UUID data
- You only call v4 on current Node or browsers; crypto.randomUUID() provides the standard random UUID with no package
- Short user-facing strings are the requirement; UUID text is fixed to its standard shape, while Nano ID lets you choose length and alphabet
- Your toolchain requires a supported CommonJS package; the README says CommonJS support ended in version 12 even though require() happened to work in our Node 22 check
- You need generation for UUID v8; the RFC leaves v8 vendor-specific and this package intentionally validates it but provides no v8() creator
- Creation time must remain hidden from identifiers; v1, v6, and v7 carry time information, so use random v4 or another opaque scheme
Setup reality
Our fresh Node 22 sandbox installed uuid 14.0.2 in 0.4 seconds. One package used 1 MB on disk, and npm audit reported 0 known vulnerabilities at every severity. uuid declares 0 direct dependencies and 0 peer dependencies; its package is 316 KB unpacked under the MIT license. It is ESM with an exports map. ESM import worked, and require() also worked in the tested Node 22 runtime. TypeScript declarations are bundled. A complete esbuild browser import measured 10 KB minified and 3.8 KB gzipped.
There are no credentials or config files. Random versions need a cryptographic random API. Current browsers and supported Node releases provide it, while React Native and Expo need react-native-get-random-values imported before uuid or any transitive import that reaches it. The README describes version 12 and later as lacking CommonJS support. Node 22 can require some ESM modules, which explains our successful check, but older Node, Jest transforms, and bundlers may still fail. Use documented ESM imports for portable version 14 code.
Choose the version based on semantics. v4 is opaque and random. v7 sorts by its Unix timestamp and is usually the useful database choice. v5 derives the same UUID from one name and namespace using SHA-1; v3 exists for MD5 compatibility and the RFC preference quoted in the README points new work to v5. v1 and v6 carry Gregorian time and node or random-node fields. Do not promise secrecy or unpredictability from time-based formats, and keep a unique database constraint for every generated value.
Timestamp generators keep internal state when called without options. Starting in version 11, passing any options object selects a different path that does not use that internal uniqueness state. Supply a deliberate sequence when generating several v7 values for an injected millisecond. Version 14.0.2 corrects the lower-level default v7 sequence formula and two v1 byte-generation cases. parse() and stringify() use left-to-right hex-byte order; database drivers with mixed-endian legacy UUID storage may need an explicit conversion outside this package.
Patterns
Create an opaque random UUID generate-random-v4
import { v4 as uuidv4 } from "uuid";
const id = uuidv4();Use crypto.randomUUID() instead when this is the package's only job and every target runtime supports it.
Create a time-ordered database ID generate-sortable-v7
import { v7 as uuidv7 } from "uuid";
const id = uuidv7();UUID v7 carries a Unix timestamp and sorts by creation time. It does not hide when the value was generated.
Derive a stable UUID from a URL derive-deterministic-v5
import { v5 as uuidv5 } from "uuid";
const id = uuidv5(
"https://example.com/customers/42",
uuidv5.URL,
);The same name and namespace always produce the same UUID. Changing either creates a different identity domain.
Generate an MD5 namespace UUID for compatibility derive-legacy-v3
import { v3 as uuidv3 } from "uuid";
const id = uuidv3("service.example", uuidv3.DNS);The README quotes RFC guidance preferring SHA-1 version 5 when backward compatibility does not require version 3.
Accept only version 7 UUIDs validate-one-version
import { validate, version } from "uuid";
function isUuidV7(value) {
return validate(value) && version(value) === 7;
}Call validate() before version(); version() throws TypeError for invalid input. NIL and MAX have special reported versions.
Parse UUID text into 16 bytes convert-string-to-bytes
import { parse } from "uuid";
const bytes = parse("6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b");
console.log(bytes instanceof Uint8Array);Byte order follows the UUID string's hex pairs from left to right. Check a database driver's legacy UUID byte ordering separately.
Format bytes as UUID text convert-bytes-to-string
import { stringify } from "uuid";
const bytes = Uint8Array.of(
0x6e, 0xc0, 0xbd, 0x7f, 0x11, 0xc0, 0x43, 0xda,
0x97, 0x5e, 0x2a, 0x8a, 0xd9, 0xeb, 0xae, 0x0b,
);
const id = stringify(bytes);stringify() throws if the selected bytes do not encode a valid RFC UUID variant and version.
Generate UUID bytes into existing storage write-into-a-buffer
import { v4 as uuidv4 } from "uuid";
const buffer = new Uint8Array(32);
uuidv4(undefined, buffer, 8);
const uuidBytes = buffer.subarray(8, 24);The function returns the supplied buffer when one is provided. Confirm offset capacity before writing.
Control a version 7 timestamp and sequence generate-v7-with-options
import { v7 as uuidv7 } from "uuid";
const id = uuidv7({
msecs: Date.UTC(2026, 7, 23),
seq: 1,
});Passing options disables the generator's internal uniqueness state. Provide sequence and randomness deliberately for repeated values at one timestamp.
Reorder an existing v1 UUID for sorting convert-v1-to-v6
import { v1ToV6, v6ToV1 } from "uuid";
const v6Id = v1ToV6(v1Id);
const original = v6ToV1(v6Id);The conversion preserves UUID fields while changing their layout. Both formats still expose time-related information.
Install random values before uuid in React Native prepare-react-native
import "react-native-get-random-values";
import { v4 as uuidv4 } from "uuid";
const id = uuidv4();Place the polyfill first in the entry module. A transitive uuid import that runs earlier can still trigger the getRandomValues error.
Create UUIDs in a shell generate-from-the-cli
npx uuid
npx uuid v7
npx uuid v5 example.com DNSThe no-argument command creates v4. The namespace command accepts DNS or URL constants as documented.
Alternatives
| Package | Registry | Pick it when |
|---|---|---|
| nanoid | npm | Use it when compact URL-friendly random strings matter and no external system requires UUID format. |
| ulid | npm | Use it when the project has standardized on ULID's sortable 26-character representation. |
| @paralleldrive/cuid2 | npm | Use it when Cuid2's string format and documented collision model fit better than RFC UUID versions. |
More utils guides
lru-cache · type-fest · ajv · p-limit · find-up · js-yaml · the whole shelf →
How this guide is made: grounded in the library's documentation, release notes, changelog, and issue history, on a fixed rubric — not a hands-on install of every release. The 50 most-downloaded entries are additionally install-verified in clean containers. Corrections: contact the desk.