Skip to main content
Warning: You are using the test version of PyPI. This is a pre-production deployment of Warehouse. Changes made here affect the production instance of TestPyPI (
Help us improve Python packaging - Donate today!

Generate secure multiword passwords/passphrases, inspired by XKCD

Project Description


A flexible and scriptable password generator which generates strong passphrases, inspired by XKCD 936:

$ xkcdpass
> correct horse battery staple


xkcdpass can be easily installed using pip:

pip install xkcdpass

or manually:

python install


The latest development version can be found on github:

Contributions welcome and gratefully appreciated!


Python 2.4+ (Python 3.x compatible)

Running xkcdpass

xkcdpass can be called with no arguments:

$ xkcdpass
> pinball previous deprive militancy bereaved numeric

which returns a single password, using the default dictionary and default settings. Or you can mix whatever arguments you want:

$ xkcdpass --count=5 --acrostic='chaos' --delimiter='|' --min=5 --max=6 --valid_chars='[a-z]'
> collar|highly|asset|ovoid|sultan
> caper|hangup|addle|oboist|scroll
> couple|honcho|abbot|obtain|simple
> cutler|hotly|aortae|outset|stool
> cradle|helot|axial|ordure|shale

which returns

  • --count=5 5 passwords to choose from
  • --acrostic='chaos' the first letters of which spell ‘chaos’
  • --delimiter='|' joined using ‘|’
  • --min=5 --max=6 with words between 5 and 6 characters long
  • --valid_chars='[a-z]' using only lower-case letters (via regex).

A concise overview of the available xkcdpass options can be accessed via:

xkcdpass --help

Usage: xkcdpass [options]

    -h, --help
                                show this help message and exit
    -w WORDFILE, --wordfile=WORDFILE
                                List of valid words for password
                                Minimum length of words to make password
                                Maximum length of words to make password
    -n NUMWORDS, --numwords=NUMWORDS
                                Number of words to make password
    -i, --interactive
                                Interactively select a password
    -v VALID_CHARS, --valid_chars=VALID_CHARS
                                Valid chars, using regexp style (e.g. '[a-z]')
    -V, --verbose
                                Report various metrics for given options
    -a ACROSTIC, --acrostic=ACROSTIC
                                Acrostic to constrain word choices
    -c COUNT, --count=COUNT
                                number of passwords to generate
    -d DELIM, --delimiter=DELIM
                                separator character between words

A large wordlist is provided for convenience, but the generator can be used with any word file of the correct format: a file containing one ‘word’ per line. The default word file can be found in xkcdpass/static/default.txt.

The default word list is derived mechanically from 12Dicts by Alan Beale. It is the understanding of the author of xkcdpass that purely mechanical transformation does not imbue copyright in the resulting work. The documentation for the 12Dicts project at contains the following dedication:

The 12dicts lists were compiled by Alan Beale. I explicitly release them to the public domain, but request acknowledgment of their use.

Using xkcdpass as an imported module

The built-in functionality of xkcdpass can be extended by importing the module into python scripts. An example of this usage is provided in, which randomly capitalises the letters in a generated password. demonstrates integration of xkcdpass into a Django project, generating password suggestions as JSON to be consumed by a Javascript front-end.

A simple use of import:

from xkcdpass import xkcd_password as xp

# create a wordlist from the default wordfile
# use words between 5 and 8 letters long
wordfile = xp.locate_wordfile()
mywords = xp.generate_wordlist(wordfile=wordfile, min_length=5, max_length=8)

# create a password with the acrostic "face"
print(xp.generate_xkcdpassword(mywords, acrostic="face"))

When used as an imported module, generate_wordlist() takes the following args (defaults shown):


While generate_xkcdpassword() takes:

delimiter=" "


This is free software: you may copy, modify, and/or distribute this work under the terms of the BSD 3-Clause license. See the file LICENSE.BSD for details. -

Release History

This version
History Node


Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Hash SHA256 Hash Help Version File Type Upload Date
(221.9 kB) Copy SHA256 Hash SHA256
Source Oct 1, 2015

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting