Installation

Supported Platforms

Passlib requires Python 3.5 or newer. It is known to work with the following Python implementations:

Warning

Passlib 1.8 dropped support for Python 2.x, 3.3, and 3.4; If you need support for Python 2.6 - 3.4, use the Passlib 1.7.x series.

  • CPython 3 – v3.5 or newer.
  • PyPy3 – v5.3 or newer.

Passlib should work with all operating systems and environments, as it contains builtin fallbacks for almost all OS-dependant features. Google App Engine is supported as well.

Changed in version 1.8: Support for Python 2.x, 3.3, and 3.4 was dropped. Jython no longer listed, until it has a Python 3 compatible for testing.

Changed in version 1.7: Support for Python 2.5, 3.0-3.2 was dropped. Support for PyPy 1.x was dropped.

Optional Libraries

  • bcrypt

    If installed, this will be used to handle :class:~passlib.hash.bcrypt` and bcrypt_sha256 hashes. If your system lacks crypt.crypt() support for bcrypt hashes, this library is required in order for passlib to provide bcrypt support.

    Use pip install passlib[bcrypt] to get the recommended bcrypt setup.

  • argon2_cffi (>= 18.2.0), or argon2pure (>= 1.3)

    If any of these packages are installed, they will be used to provide support for the argon2 hash algorithm. argon2_cffi is currently the recommended option.

    Use pip install passlib[argon2] to get the recommended argon2 setup.

  • Cryptography

    If installed, will be used to enable encryption of TOTP secrets for storage (see passlib.totp).

    Use pip install passlib[totp] to get the recommended TOTP setup.

  • fastpbkdf2

    If installed, will be used to greatly speed up pbkdf2_hmac(), and any pbkdf2-based hashes.

  • SCrypt (>= 0.6)

    If installed, this will be used to provide support for the scrypt hash algorithm. If not installed, a MUCH slower builtin reference implementation will be used.

Changed in version 1.8: Dropped support for py-bcrypt and bcryptor backends.

Changed in version 1.7: Added fastpbkdf2, cryptography, argon2_cffi, argon2pure, and scrypt support. Removed M2Crypto support.

Installation Instructions

Caution

All PyPI releases are signed with the gpg key 4D8592DF4CE1ED31.

To install from PyPi using pip:

pip install passlib

To install from the source using setup.py:

python setup.py install

Testing

Passlib contains a comprehensive set of unittests (about 38% of the total code), which provide nearly complete coverage, and verification of the hash algorithms using multiple external sources (if detected at runtime).

All unit tests are contained within the passlib.tests subpackage, and are designed to be run using the Nose unit testing library.

Once Passlib and Nose have been installed, the main suite of tests may be run using:

nosetests --tests passlib.tests

By default, this runs the main battery of tests, but omits some additional ones (such as internal cross-checks, and mock-testing of features not provided natively by the host OS). To run these tests as well, set the following environmental variable:

PASSLIB_TEST_MODE="full" nosetests --tests passlib.tests

To run a quick check to confirm just basic functionality, with a pared-down set of tests:

PASSLIB_TEST_MODE="quick" nosetests --tests passlib.tests

Tests may also be run via setup.py test or the included tox.ini file. The tox.ini file is used to test passlib before each release, and contains a number different environment setups. These tests require tox 2.5 or later.

Building the Documentation

The latest copy of this documentation should always be available online at https://passlib.readthedocs.io. If you wish to generate your own copy of the documentation, you will need to:

  1. Download the Passlib source, extract it, and cd into the source directory.
  2. Install all the dependencies required via pip install -e .[build_docs].
  3. Run python setup.py build_sphinx.
  4. Once Sphinx completes its run, point a web browser to the file at SOURCE/build/sphinx/html/index.html to access the Passlib documentation in html format.