Skip to main content

Passphrases you will remember.

Project description


Passphrases to remember…

Build Status | documentation | sources | issues

diceware is a passphrase generator following the proposals of Arnold G. Reinhold on . It generates passphrases by concatenating words randomly picked from wordlists. For instance:

$ diceware

The passphrase contains by default six words (with first char capitalized) without any separator chars. Optionally you can let diceware insert special chars into the passphrase.


This Python package can be installed via pip:

$ pip install diceware

The exact way depends on your operating system.


Once installed, use --help to list all available options:

$ diceware --help
Create a passphrase

positional arguments:
  INFILE                Input wordlist. `-' will read from stdin.

optional arguments:
  -h, --help            show this help message and exit
  -n NUM, --num NUM     number of words to concatenate. Default: 6
  -c, --caps            Capitalize words. This is the default.
  --no-caps             Turn off capitalization.
  -s NUM, --specials NUM
                        Insert NUM special chars into generated word.
  -d DELIMITER, --delimiter DELIMITER
                        Separate words by DELIMITER. Empty string by default.
  -r SOURCE, --randomsource SOURCE
                        Get randomness from this source. Possible values:
                        `realdice', `system'. Default: system
  -w NAME, --wordlist NAME
                        Use words from this wordlist. Possible values:
                        `en_8k', `en_orig'. Wordlists are stored in the folder
                        displayed below. Default: en_8k
  --version             output version information and exit.

With -n you can tell how many words are supposed to be picked for your new passphrase:

$ diceware -n 1

$ diceware -n 2

You can diceware additionally let generate special chars to replace characters in the ‘normal’ passphrase. The number of special chars generated can be determined with the -s option (default is zero):

$ diceware -s 2

Here "%" and "#" are the special chars.

Special chars are taken from the following list:


Please note that several special chars might replace the same original char, resulting in a passphrase with less special chars than requested.

With -d you can advise diceware to put a delimiter string between the words generated:

$ diceware -d "_"

By default we use the empty string as delimiter, which is good for copying via double click on Linux systems. But other delimiters might make your passphrases more readable.

By default the single phrase words are capitalized, i.e. the first char of each word is made uppercase. This does not neccessarily give better security (1 bit at most), but it helps reading a phrase.

You can nevertheless disable caps with the --no-caps option:

$ diceware --no-caps

This leads to lower-case passphrases, maybe easier to type on smart phones or similar.

diceware supports also different sources of randomness, which can be chosen with the -r <SOURCENAME> or --randomsource <SOURCENAME> option. Use the --help option to list all valid values for this option.

By default we use the random.SystemRandom class of standard Python lib but you can also bring your own dice to create randomness:

$ diceware -r realdice
Please roll 5 dice (or a single dice 5 times).
What number shows dice number 1? 2
What number shows dice number 2? 3

We support even sources of randomness from other packages. See the documentation for more details.

diceware comes with an English wordlist (the ‘diceware8k’ list) provided by Arnold G. Reinhold, which will be used by default and contains 8192 different words.

Apart from that diceware is packaged with the “original” 7776 word list provided by Mr. Reinhold. You can enable a certain (installed) wordlist with the -w option:

$ diceware --wordlist en_orig

See diceware --help for a list of all installed wordlists.

If you do not like the wordlists provided, you can use your own one. Any INFILE provided will be parsed line by line and each line considered a possible word. For instance:

$ echo -e "hi\nhello\n" > mywordlist.txt
$ diceware mywordlist.txt

With dash (-) as filename you can pipe in wordlists:

$ echo -e "hi\nhello\n" > mywordlist.txt
$ cat mywordlist.txt | diceware -

In custom wordlists we take each line for a valid word and ignore empty lines (i.e. lines containing whitespace characters only). Oh, and we handle even PGP-signed wordlists.

What is it good for?

Normally, diceware passphrases are easier to remember than shorter passwords constructed in more or less bizarre ways. But at the same time diceware passphrases provide more entropy as xkcd can show with the famous ‘936’ proof:

The standard english wordlist of this diceware implementation contains 8192 = 2**13 different english words. It is a copy of the Diceware8k list provided by Mr. Reinhold. Therefore, picking a random word from this list gives an entropy of 13 bits. Picking six words means an entropy of 6 x 13 = 73 bits.

The special chars replacing chars of the originally created passphrase give some more entropy (the more chars you have, the more additional entropy), but not much. For instance, for a sixteen chars phrase you have sixteen possibilities to place one of the 36 special chars. That makes 36 x 16 possibilitities or an entropy of about 9.17 you can add. To get an entropy increase of at least 10 bits, you have to put a special char in a phrase with at least 29 chars (while at the same time an additional word would give you 13 bits of extra entropy). Therefore you might think again about using special chars in your passphrase.

Is it secure?

The security level provided by Diceware depends heavily on your source of random. If the delivered randomness is good, then your passphrases will be very strong. If instead someone can foresee the numbers generated by a random number generator, your passphrases will be surprisingly weak.

This Python implementation uses (by default) the random.SystemRandom source provided by Python. On Un*x systems it accesses /dev/urandom. You might want to follow reports about manipulated random number generators in operating systems closely.

The Python API of this package allows usage of other sources of randomness when generating passphrases. This includes real dice. See the -r option.

Developer Install

Developers want to fork me on github:

$ git clone

We recommend to create and activate a virtualenv first:

$ cd diceware/
$ virtualenv -p /usr/bin/python3.3 py33
$ source py33/bin/activate
(py33) $

We support Python versions 2.6, 2.7, 3.2, 3.3, 3.4, pypy.

Now you can create the devel environment:

(py33) $ python dev

This will fetch test packages (py.test). You should be able to run tests now:

(py33) $ py.test

If you have also different Python versions installed you can use tox for using them all for testing:

(py33) $ pip install tox   # only once
(py33) $ tox

Should run tests in all supported Python versions.

Documentation Install

The docs can be generated with Sphinx. The needed packages are installed via:

(py33) $ python docs

To create HTML you have to go to the docs/ directory and use the prepared Makefile:

(py33) $ cd docs/
(py33) $ make

This should generate the docs in docs/_build/html/.


Arnold G. Reinhold deserves all merits for the working parts of Diceware. The non-working parts are certainly my fault.

People that helped spotting bugs, providing solutions, etc.:

  • Conor Schaefer (conorsch)
  • Rodolfo Gouveia suggested to activate the --delimiter option.
  • drebs provided patches and discussion for different sources of randomness.

Many thanks to all of them!


This Python implementation of Diceware, (C) 2015 Uli Fouquet, is licensed under the GPL v3+.

The Copyright for the Diceware idea and the Diceware8k list are Copyright by Arnold G. Reinhold. See file LICENSE for details.


0.5 (2015-08-05)

  • New option -r, --randomsource. We support a pluggable system to define alternative sources of randomness. Currently supported sources: "system" (to retrieve randomness from standard library, default) and realdice, which allows use of real dice.
  • New option -w, --wordlist. We now provide several wordlists for users to choose from. Own wordlists could already be fed to diceware before. By default we still use the 8192 words list from
  • Rename SRC_DIR to WORDLISTS_DIR (reflecting what it stands for).
  • Use also flake8 with tox.
  • Pass options to get_passphrase() instead of a bunch of single args.
  • Output wordlists dir in help output.

0.4 (2015-03-30)

  • Add –delimiter option (thanks to Rodolfo Gouveia).

0.3.1 (2015-03-29)

  • Turned former diceware module into a Python package. This is to fix bug #1 Wordlists aren’t included during installation, this time really. Wordlists will from now on be stored inside the diceware package. Again many thanks to conorsch who digged deep into the matter and also came up with a very considerable solution.
  • Use readthedocs theme in docs.

0.2 (2015-03-27)

  • Minor documentation changes.
  • Updated copyright infos.
  • Add support for custom wordlists.

0.1 (2015-02-18)

  • Initial release.

Project details

Download files

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

Files for diceware, version 0.5
Filename, size File type Python version Upload date Hashes
Filename, size diceware-0.5-py2.py3-none-any.whl (76.6 kB) File type Wheel Python version 3.3 Upload date Hashes View
Filename, size diceware-0.5.tar.gz (86.3 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page