In the mongosh shell, MongoDB's built-in UUID() helper generates a version 4 identifier as a native BSON Binary value, so you get a MongoDB UUID without installing a single driver or library. It still displays with the familiar hyphenated formatting, but MongoDB stores it as 16 raw bytes internally rather than a 36-character string. Below you'll find copy-paste ready mongosh commands for generating a UUID, converting an existing UUID string into the BSON type, and the driver-level options for generating UUIDs from application code.
How to Generate a UUID in MongoDB
The simplest way to generate a UUID in MongoDB is the built-in UUID() helper, available directly in the mongosh shell — no driver, package, or extension required. To get a truly random value you generate it in application code, and the mysql uuid page shows how to insert it.
const id = UUID();
print(id);
// Output: UUID("550e8400-e29b-41d4-a716-446655440000")Explanation
UUID()with no arguments generates a random version 4 identifier — the same algorithm used bycrypto.randomUUID()in JavaScript oruuid.uuid4()in Python.- The value returned is a BSON
Binarysubtype 4 object, not a plain string, so it's stored as 16 raw bytes rather than a 36-character string. print(id)shows the value with the familiar hyphenated UUID formatting even though MongoDB stores it in binary form internally.- Assign
UUID()directly as a field value — including_id— when inserting a document from the shell.
Convert a String to a UUID in MongoDB
A UUID sent as a string — from an API request or an application layer — needs to pass through the same UUID() constructor to become MongoDB's native BSON UUID type. Where gen_random_uuid() is unavailable, the postgres uuid generator page falls back to uuid-ossp and its older functions.
const id = UUID("550e8400-e29b-41d4-a716-446655440000");
print(id);
// Output: UUID("550e8400-e29b-41d4-a716-446655440000")
// Convert it back to a plain string
print(id.toString());
// Output: "UUID('550e8400-e29b-41d4-a716-446655440000')"Explanation
- Passing a string to
UUID(...)parses and validates it, converting the 36-character text into the same BSONBinarysubtype 4 value thatUUID()produces on its own. - Use this form when querying by an existing UUID — for example
db.users.findOne({ _id: UUID("550e8400-e29b-41d4-a716-446655440000") }). - An improperly formatted string throws an error immediately, so wrap untrusted input in a try/catch when converting values from user requests.
.toString()converts the BSON UUID back into a readable string form when you need to log it or return it in a JSON response.
Other Options for Generating UUIDs in MongoDB
The mongosh shell is convenient for testing, but production documents are almost always inserted from application code, so drivers expose their own way to create a MongoDB UUID.
const { MongoClient, UUID } = require('mongodb');
const crypto = require('crypto');
// Generate a UUID with Node's built-in crypto module, then
// wrap it as MongoDB's BSON UUID (Binary subtype 4) type
const id = new UUID(crypto.randomUUID());
await db.collection('users').insertOne({ _id: id, name: 'Ada Lovelace' });Explanation
- The Node.js MongoDB driver's
UUIDclass accepts any RFC 4122 string — including one generated bycrypto.randomUUID()— and stores it as a BSONBinaryvalue. - PyMongo follows the same pattern: generate an identifier with
uuid.uuid4(), then wrap it withbson.Binary.from_uuid()before inserting. - Both approaches produce the exact same on-disk format as the shell's
UUID()helper, so documents created from a driver and frommongoshstay fully compatible. - Keep the driver's UUID representation setting consistent across your application so string-to-UUID conversions round-trip correctly.