Javascript UUID Function

[UPDATE – 1/3/2010: For the latest/greatest implementation of a JavaScript UUID function, please check out my node-uuid project.  Any future improvements/enhancements to this code will be made there.]

[UPDATE – 9/1/2011: ‘Seeing reports of UUID collisions in the wild.  Johannes Baagoe has a write up on why Math.random() can’t be trusted.  I’m not entirely sure I buy this, but I’m certainly less confident than before about the uniqueness of UUIDs generated using only Math.random().]

Here’s a little JavaScript treat: Math.uuid.js is a function for generating different flavors of UUIDs in JavaScript. The function supports RFC 4122-compliant UUIDs (or GUIDS), like this:


… as well as non-standard random IDs of arbitrary length and radix. For examples of the types of IDs it can generate, or to see performance data, check out the Math.uuid.js Test page.

I put this together after discovering that nobody had published a really thin javascript implementation for generating UUIDs. Googling around turns up several decent scripts, but all of these suffered from one drawback or another (IMHO). One common problem results from trying to produce “version 1” ids, which the RFC defines in a way that is supposed to guarantee the uniqueness of the ID. But javascript doesn’t have an API for getting a guaranteed-unique anything – the best you can do is use Math.random() as a hack workaround which, strictly speaking, shouldn’t be used when uniqueness must be guaranteed. Using JavaScript to generate a version 1 UUID could be construed as misleading.

The more correct solution is to do what Math.uuid.js does – create “version 4” ids, which are defined as randomly generated (see RFC 4122, section 4.4). This avoids making an unfulfilled promise of universal uniqueness, while allowing for much simpler code. Also, in javascript where Math.random() has to be used for UUID generation, the theoretical uniqueness of these ids is better than version 1 implementations since all 122 bits of field data are randomly generated. That makes for a staggering 5.3 x 10^^36 possible ids. If every person on the planet filled up a terabyte hard drive with nothing but random UUIDs, there would only be a one in 7 trillion chance that two of the UUIDs would be the same. That’s the theory.

The practice is probably a little different. The uniqueness depends on how random the numbers generated by Math.random() are. Generating truly random numbers is a notoriously tricky problem, solved in different (imperfect) ways across browser platforms and OSes. It’s difficult to say for sure what the real-world uniqueness of these numbers ends up being, but I suspect it’s more than sufficient for most purposes. Regardless, this is a weakness that all javascript UUID generators will be subject to, unless they rely on an externally-provided unique value. For example, one could use AJAX to fetch UUIDs generated by a site like, but that has it’s own set of issues.

Update 1/22/10: Math.uuid.js includes an Math.uuid2 Math.uuidCompact – an alternate implementation for RFC4122v4 UUIDs designed to be as compact as possible, and Math.uuidFast() – an implementation designed for performance.

Update 06/03/10: Several people have expressed concern over how random the Math.random() method is. (E.g. “If two clients load the random() lib at the same time, will they start with the same seed?”) After doing a bit of research into how various OSes handle random # generation , I’m pretty satisfied that this unlikely to be an issue.  Seeding is done from a variety of sources of almost pure random numbers – mouse movement, built-in hardware support (e.g. by measuring noise in electrical circuits), various unique device IDs, BIOS checksums, memory usage statistics… and so on.


27 responses to “Javascript UUID Function”

  1. Unfortunately, I can’t integrate OSL code in an MIT licensed distribution because of its viral clause. Sorry. I’m building a collection of portable JavaScript “modules” and promoting a standard for module loaders. Please let me know if you read the license differently.

  2. @kris: Can you be more specific about the license incompatabilities? Any suggestions as to which license would be most appropriate for something like this?

    @stephen: Sure. If you have a web app with a data model on the client, this allows the client to assign permanent IDs to objects when they are created, rather than having to issue a server request to get an ID (like you would normally have to do in a more traditional architecture.)

  3. I think this has a bug that causes it to fail in IE7. IE7 does not allow you to extract characters from a string using square brackets, you have to use the .charAt() function.

    Alternatively, you could change this line:
    var c = ‘0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz’;

    to this:
    var c = ‘0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz’.split(”);

    then c is an array and should work in all browsers.

  4. Good Catch, Brian. I’ve updated the script to use the split() fix as you suggested. (If the code looks a little odd to anyone, it’s because I cache the split() version of the string on the function object. But in order to do that without requiring a cumbersome declaration outside of the function, I use arguments.callee to get the function object from within itself. It’s a little kludgy, but it keeps the method nice and self-contained.)

  5. Rodolfo :

    What’s the license of this script? GPL, MIT?

    BSD – It’s in the script source.
    Update: Now dual MIT/GPL licensed.

  6. When I run the Math.uuid.js test page in IE6 on WinXP I get a javascript error at the line below. Crome and FF work fine of course. Anybody else report/fix this problem.

    var args = ARGS.shift(), length = args[0] || 0, radix = args[1] || 62;

    Here is the specifi error:
    A Runtime Error has occurred.
    Do you wish to Debug?

    Line: 33
    Error: ‘0’ is null or not an object
    Yes No

    This page is an awsome reference. I’d add this to the Wikkipedia UUID page if I know that this problem with IE is an isolated problem.

  7. @Troy – Good catch. The problem was in the test page code, not the Math.uuid() function. ‘Just a trailing comma error, *dooh*. I’ve fixed it and it should be working now. Thanks for the report!

  8. Wow! that was fast. Thanks for fixing this so quickly.

    There is one typo that I found. The linked text for RFC4122 above is RFC4142

  9. Is there a shorter version of the license text I could use along with a URL to the full license? I’d like to include a modified version of this script in some work and the license text is pretty bulky.

  10. Great, just what I was looking for for use in an Adobe AIR app that has client/server sync. Thanks much!

  11. The revised BSD license is fully GPL compatible and OSI approved. It is essentially equivalent to the MIT License, and doesn’t have a viral clause. Hope that clears things up for anybody stumbling across this!

  12. This code is now dual licensed under MIT and GPL. I’ve also shortened the verbiage to this effect in the source so it’s not so unwieldy.

  13. In regards to compliance with RFC 4122, 122 bits need to be independently randomly generated. Although I have not confirmed this, I think the reason is to (partly) deal with the issue of uniqueness in pseudo-random number generators. The Math.uuid.js code generates 31 random hex values. By generating random hex values instead of random bit values, are we not increasing the odds of generating duplicate UUIDs?

  14. @David

    That’s a really good question. The only verbiage I see in rfc4122 about this is in section 4.4, where it says, “Set all the other bits to randomly (or pseudo-randomly) chosen values.” But I don’t read this as saying each bit must be generated by a unique call to a random number function. Random # generators are “in the business” of creating numbers where each bit is randomly set. So the hex values I’m using are simply clusters of 4 random bits produced by the Math.random() function.

    In fact, there’s a good argument that *fewer* calls to Math.random() is better. Pseudo-random # generators are typically evaluated based on how many #’s they can produce before repeating. So by minimizing the # of calls, we’re maximizing the number of UUIDs we create before the generator begins repeating itself.

  15. @George: Good catch, thanks! I’ve fixed uuidFast.

    BTW, it seems like Math.random() is the biggest performance bottleneck. Do you have any feel for how David Bau’s implementation compares to the native one?

    Also, is there really a need for a better RNG? I would expect the native implementations to be pretty good already. But I don’t have any concrete data for that assumption.

  16. I didn’t benchmark Bau’s implementation of Math.random(), but it seems reasonable. I would expect it to be slower than most browser’s native implementation of Math.random(), but that the results are higher quality. He clearly knows quite a bit of math.

    His Math.seedrandom() is very slow, however, if you let it gather entropy by walking the window object: about 700ms on Firefox, 100ms on other browsers that I tried. Much better to call his seedrandom with some server-generated random string like, perhaps, a real UUID or two 🙂

  17. Thank you for that.
    This really help to solve a task of tracking what a user does quick and dirty 🙂

  18. Regarding your update on 6/3/2010 (I think this may have been in response to an e-mail I had written you around that time) – I don’t actually think most JS implementations actually use entropy sources in the OS. At least, I checked V8 specifically, and they seed their random number generator using the system time. Is it even possible to get to the OS entropy sources from the browser?