Getting started

Development dependencies

Working on cryptography requires the installation of a small number of development dependencies in addition to the dependencies for Installation. These are handled by the use of tox, which can be installed with pip.

$ # Create a virtualenv and activate it
$ # Set up your cryptography build environment
$ pip install tox
$ # Specify your Python version here.
$ tox -e py310

OpenSSL on macOS

You must have installed OpenSSL via Homebrew or MacPorts and must set CFLAGS and LDFLAGS environment variables before running tox otherwise pip will fail with include errors.

For example, with Homebrew:

$ env LDFLAGS="-L$(brew --prefix openssl@1.1)/lib" \
    CFLAGS="-I$(brew --prefix openssl@1.1)/include" \
    tox -e py310

Alternatively for a static build you can specify CRYPTOGRAPHY_SUPPRESS_LINK_FLAGS=1 and ensure LDFLAGS points to the absolute path for the OpenSSL libraries before calling pip.

Tip

You will also need to set these values when Building documentation.

Running tests

cryptography unit tests are found in the tests/ directory and are designed to be run using pytest. tox automatically invokes pytest:

$ tox -e py310
...
62746 passed in 220.43 seconds

You can also verify that the tests pass on other supported Python interpreters with tox. For example:

$ tox
...
ERROR:   pypy: InterpreterNotFound: pypy
 py38: commands succeeded
 py39: commands succeeded
 py310: commands succeeded
 py311: commands succeeded
 docs: commands succeeded
 pep8: commands succeeded

You may not have all the required Python versions installed, in which case you will see one or more InterpreterNotFound errors.

Building documentation

cryptography documentation is stored in the docs/ directory. It is written in reStructured Text and rendered using Sphinx.

Use tox to build the documentation. For example:

$ tox -e docs
...
docs: commands succeeded
congratulations :)

The HTML documentation index can now be found at docs/_build/html/index.html.