Skip to content


Subversion checkout URL

You can clone with
Download ZIP
HTML Other
Branch: master
Failed to load latest commit information.
data deleted old password list
demo refactor matching, scoring, init, frequency_lists, adjacency_graphs i…
scripts refactor matching, scoring, init, frequency_lists, adjacency_graphs i…
test refactor matching, scoring, init, frequency_lists, adjacency_graphs i…
tools added NOTICE.txt for tools/closure
.gitignore Simplify async loading scripts.
.npmignore corrected entries in .npmignore
NOTICE.txt heh, forgot to update the README w/ an actual blog link README update for module.exports change
adjacency_graphs.js refactor matching, scoring, init, frequency_lists, adjacency_graphs i…
bower.json remove version from bower.json + README tweaks Simplify async loading scripts.
frequency_lists.js refactor matching, scoring, init, frequency_lists, adjacency_graphs i… refactor matching, scoring, init, frequency_lists, adjacency_graphs i… refactor matching, scoring, init, frequency_lists, adjacency_graphs i…
package.json refactor: use namespace objects refactor matching, scoring, init, frequency_lists, adjacency_graphs i…
zxcvbn-async-bower.js Simplify async loading scripts.
zxcvbn-async.js update package.json to point to dropbox/zxcvbn
zxcvbn.js refactor matching, scoring, init, frequency_lists, adjacency_graphs i…


zxcvbn, named after a crappy password, is a JavaScript password strength estimation library. Use it to implement a custom strength bar on a signup form near you!

zxcvbn attempts to give sound password advice through pattern matching and conservative entropy calculations. It finds 10k common passwords, common names and surnames according to US census data, common English words, and common patterns like dates, repeats (aaa), sequences (abcd), and QWERTY patterns.

For full motivation, see:


zxcvbn automatically detects and supports CommonJS (node, browserify) and AMD (RequireJS). In the absence of those, it adds a single function zxcvbn to the global namespace.


Install node and bower if you haven't already. This won't make your codebase dependent on node.

Get zxcvbn:

cd /path/to/project/root # your index.html lives here
bower install zxcvbn

Add this script to your index.html:

<script type="text/javascript" src="bower_components/zxcvbn/zxcvbn-async-bower.js">

That's it! To make sure it loaded properly, open index.html in a browser and type zxcvbn('Tr0ub4dour&3') into the console.

To pull in updates and bug fixes:

bower update zxcvbn

How loading works: zxcvbn-async-bower.js is a tiny script. On window.load, after your page loads and renders, it'll fetch zxcvbn.js in the background, which is more like 680kb (320kb gzipped), most of which is a series of dictionaries.

680kb may seem large for a script, but since it loads in the background, and because passwords come later in most registration flows, we've never had an issue.

Node / npm / browserify

zxcvbn works identically on the server.

$ npm install zxcvbn
$ node
> var zxcvbn = require('zxcvbn');
> zxcvbn('Tr0ub4dour&3');

And should automatically work with browserify. The easiest browserify setup is to include zxcvbn.js in your main bundle. If the size of the script is an issue, consider instead adding a loading script modeled after zxcvbn-async.js to your main bundle, such that zxcvbn.js loads asynchronously in the background without blocking page load. See comments in zxcvbn-async.js -- you'll likely only need to change ZXCVBN_SRC to make it work.


Add zxcvbn.js to your project (using bower or direct download) and import as usual:

requirejs(["relpath/to/zxcvbn"], function (zxcvbn) {

Note: zxcvbn-async.js is for manual installations. There is no need to add it to a RequireJS setup, which already provides the same asynchronous loading support.

Manual installation

Copy zxcvbn.js and zxcvbn-async.js into your codebase.

Add to your index.html:

<script type="text/javascript" src="path/to/zxcvbn-async.js">

Open zxcvbn-async.js and edit the ZXCVBN_SRC variable to point to wherever you put zxcvbn.js. If zxcvbn.js sits at the top-level directory of your project, it'll work as-is.

Note that zxcvbn.js can also be included directly:

<script type="text/javascript" src="zxcvbn.js">

But this isn't recommended, as the 680k download will block your initial page load. Note: the advantage of using zxcvbn-async.js over the HTML5 async script attribute is that it works in old browsers.


zxcvbn(password, user_inputs)

It takes one required argument, a password, and returns a result object. The result includes a few properties:

result.entropy            # bits

result.crack_time         # estimation of actual crack time, in seconds.

result.crack_time_display # same crack time, as a friendlier string:
                          # "instant", "6 minutes", "centuries", etc.

result.score              # [0,1,2,3,4] if crack time is less than
                          # [10**2, 10**4, 10**6, 10**8, Infinity].
                          # (useful for implementing a strength bar.)

result.match_sequence     # the list of patterns that zxcvbn based the
                          # entropy calculation on.

result.calc_time          # how long it took to calculate an answer,
                          # in milliseconds. usually only a few ms.

The optional user_inputs argument is an array of strings that zxcvbn will add to its internal dictionary. This can be whatever list of strings you like, but is meant for user inputs from other fields of the form, like name and email. That way a password that includes the user's personal info can be heavily penalized. This list is also good for site-specific vocabulary.


Bug reports and pull requests welcome!

zxcvbn is written in CoffeeScript and Python. zxcvbn.js is built with, which compiles CoffeeScript into JavaScript, then JavaScript into efficient, minified JavaScript.

For development, include these scripts instead of zxcvbn.js:

<script type="text/javascript" src="adjacency_graphs.js">
<script type="text/javascript" src="frequency_lists.js">
<script type="text/javascript" src="matching.js">
<script type="text/javascript" src="scoring.js">
<script type="text/javascript" src="init.js">

Data lives in the first two scripts. These are produced by:

scripts/,, and make up the rest of the library.

init.js needs to come last, otherwise script order doesn't matter.

I recommend setting up coffee-mode in emacs, or whatever equivalent, so that CoffeeScript compiles to js on save. Otherwise you'll need to repetitively run compile_and_minify.js


Dropbox for supporting open source!

Mark Burnett for releasing his 10k top passwords list and for his 2006 book, Perfect Passwords: Selection, Protection, Authentication.

Wiktionary contributors for building a frequency list of English as used in television and movies.

Researchers at Concordia University for studying password meters rigorously and recommending zxcvbn.

And xkcd for the inspiration <3

Something went wrong with that request. Please try again.