# 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.