1Installation 2============ 3 4You can install ``cryptography`` with ``pip``: 5 6.. code-block:: console 7 8 $ pip install cryptography 9 10Supported platforms 11------------------- 12 13Currently we test ``cryptography`` on Python 2.7, 3.6+, 14PyPy 7.3.1, and PyPy3 7.3.1 on these operating systems. 15 16* x86-64 CentOS 7.x 17* x86-64 & AArch64 CentOS 8.x 18* x86-64 Fedora (latest) 19* x86-64 macOS 10.15 Catalina 20* x86-64 & AArch64 Ubuntu 18.04, 20.04 21* x86-64 Ubuntu rolling 22* x86-64 Debian Stretch (9.x), Buster (10.x), Bullseye (11.x), and Sid 23 (unstable) 24* x86-64 Alpine (latest) 25* 32-bit and 64-bit Python on 64-bit Windows Server 2019 26 27We test compiling with ``clang`` as well as ``gcc`` and use the following 28OpenSSL releases: 29 30* ``OpenSSL 1.1.0-latest`` 31* ``OpenSSL 1.1.1-latest`` 32 33 34Building cryptography on Windows 35-------------------------------- 36 37The wheel package on Windows is a statically linked build (as of 0.5) so all 38dependencies are included. To install ``cryptography``, you will typically 39just run 40 41.. code-block:: console 42 43 $ pip install cryptography 44 45If you prefer to compile it yourself you'll need to have OpenSSL installed. 46You can compile OpenSSL yourself as well or use `a binary distribution`_. 47Be sure to download the proper version for your architecture and Python 48(VC2010 works for Python 2.7 while VC2015 is required for 3.6 and above). 49Wherever you place your copy of OpenSSL you'll need to set the ``LIB`` and ``INCLUDE`` 50environment variables to include the proper locations. For example: 51 52.. code-block:: console 53 54 C:\> \path\to\vcvarsall.bat x86_amd64 55 C:\> set LIB=C:\OpenSSL-win64\lib;%LIB% 56 C:\> set INCLUDE=C:\OpenSSL-win64\include;%INCLUDE% 57 C:\> pip install cryptography 58 59As of OpenSSL 1.1.0 the library names have changed from ``libeay32`` and 60``ssleay32`` to ``libcrypto`` and ``libssl`` (matching their names on all other 61platforms). ``cryptography`` links against the new 1.1.0 names by default. If 62you need to compile ``cryptography`` against an older version then you **must** 63set ``CRYPTOGRAPHY_WINDOWS_LINK_LEGACY_OPENSSL`` or else installation will fail. 64 65If you need to rebuild ``cryptography`` for any reason be sure to clear the 66local `wheel cache`_. 67 68.. _build-on-linux: 69 70Building cryptography on Linux 71------------------------------ 72 73``cryptography`` ships ``manylinux`` wheels (as of 2.0) so all dependencies 74are included. For users on pip 8.1 or above running on a ``manylinux1`` or 75``manylinux2010`` compatible distribution (almost everything except Alpine) 76all you should need to do is: 77 78.. code-block:: console 79 80 $ pip install cryptography 81 82If you are on Alpine or just want to compile it yourself then 83``cryptography`` requires a compiler, headers for Python (if you're not 84using ``pypy``), and headers for the OpenSSL and ``libffi`` libraries 85available on your system. 86 87Alpine 88~~~~~~ 89 90Replace ``python3-dev`` with ``python-dev`` if you're using Python 2. 91 92.. code-block:: console 93 94 $ sudo apk add gcc musl-dev python3-dev libffi-dev openssl-dev 95 96If you get an error with ``openssl-dev`` you may have to use ``libressl-dev``. 97 98Debian/Ubuntu 99~~~~~~~~~~~~~ 100 101Replace ``python3-dev`` with ``python-dev`` if you're using Python 2. 102 103.. code-block:: console 104 105 $ sudo apt-get install build-essential libssl-dev libffi-dev python3-dev 106 107RHEL/CentOS 108~~~~~~~~~~~ 109 110.. code-block:: console 111 112 $ sudo yum install redhat-rpm-config gcc libffi-devel python-devel \ 113 openssl-devel 114 115 116Building 117~~~~~~~~ 118 119You should now be able to build and install cryptography. To avoid getting 120the pre-built wheel on ``manylinux`` compatible distributions you'll need to 121use ``--no-binary``. 122 123.. code-block:: console 124 125 $ pip install cryptography --no-binary cryptography 126 127 128Using your own OpenSSL on Linux 129~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 130 131Python links to OpenSSL for its own purposes and this can sometimes cause 132problems when you wish to use a different version of OpenSSL with cryptography. 133If you want to use cryptography with your own build of OpenSSL you will need to 134make sure that the build is configured correctly so that your version of 135OpenSSL doesn't conflict with Python's. 136 137The options you need to add allow the linker to identify every symbol correctly 138even when multiple versions of the library are linked into the same program. If 139you are using your distribution's source packages these will probably be 140patched in for you already, otherwise you'll need to use options something like 141this when configuring OpenSSL: 142 143.. code-block:: console 144 145 $ ./config -Wl,--version-script=openssl.ld -Wl,-Bsymbolic-functions -fPIC shared 146 147You'll also need to generate your own ``openssl.ld`` file. For example:: 148 149 OPENSSL_1.1.0E_CUSTOM { 150 global: 151 *; 152 }; 153 154You should replace the version string on the first line as appropriate for your 155build. 156 157Static Wheels 158~~~~~~~~~~~~~ 159 160Cryptography ships statically-linked wheels for macOS, Windows, and Linux (via 161``manylinux``). This allows compatible environments to use the most recent 162OpenSSL, regardless of what is shipped by default on those platforms. Some 163Linux distributions (most notably Alpine) are not ``manylinux`` compatible so 164we cannot distribute wheels for them. 165 166However, you can build your own statically-linked wheels that will work on your 167own systems. This will allow you to continue to use relatively old Linux 168distributions (such as LTS releases), while making sure you have the most 169recent OpenSSL available to your Python programs. 170 171To do so, you should find yourself a machine that is as similar as possible to 172your target environment (e.g. your production environment): for example, spin 173up a new cloud server running your target Linux distribution. On this machine, 174install the Cryptography dependencies as mentioned in :ref:`build-on-linux`. 175Please also make sure you have `virtualenv`_ installed: this should be 176available from your system package manager. 177 178Then, paste the following into a shell script. You'll need to populate the 179``OPENSSL_VERSION`` variable. To do that, visit `openssl.org`_ and find the 180latest non-FIPS release version number, then set the string appropriately. For 181example, for OpenSSL 1.0.2k, use ``OPENSSL_VERSION="1.0.2k"``. 182 183When this shell script is complete, you'll find a collection of wheel files in 184a directory called ``wheelhouse``. These wheels can be installed by a 185sufficiently-recent version of ``pip``. The Cryptography wheel in this 186directory contains a statically-linked OpenSSL binding, which ensures that you 187have access to the most-recent OpenSSL releases without corrupting your system 188dependencies. 189 190.. code-block:: console 191 192 set -e 193 194 OPENSSL_VERSION="VERSIONGOESHERE" 195 CWD=$(pwd) 196 197 virtualenv env 198 . env/bin/activate 199 pip install -U setuptools 200 pip install -U wheel pip 201 curl -O https://www.openssl.org/source/openssl-${OPENSSL_VERSION}.tar.gz 202 tar xvf openssl-${OPENSSL_VERSION}.tar.gz 203 cd openssl-${OPENSSL_VERSION} 204 ./config no-shared no-ssl2 no-ssl3 -fPIC --prefix=${CWD}/openssl 205 make && make install 206 cd .. 207 CFLAGS="-I${CWD}/openssl/include" LDFLAGS="-L${CWD}/openssl/lib" pip wheel --no-binary :all: cryptography 208 209Building cryptography on macOS 210------------------------------ 211 212.. note:: 213 214 If installation gives a ``fatal error: 'openssl/aes.h' file not found`` 215 see the :doc:`FAQ </faq>` for information about how to fix this issue. 216 217The wheel package on macOS is a statically linked build (as of 1.0.1) so for 218users with pip 8 or above you only need one step: 219 220.. code-block:: console 221 222 $ pip install cryptography 223 224If you want to build cryptography yourself or are on an older macOS version, 225cryptography requires the presence of a C compiler, development headers, and 226the proper libraries. On macOS much of this is provided by Apple's Xcode 227development tools. To install the Xcode command line tools (on macOS 10.10+) 228open a terminal window and run: 229 230.. code-block:: console 231 232 $ xcode-select --install 233 234This will install a compiler (clang) along with (most of) the required 235development headers. 236 237You'll also need OpenSSL, which you can obtain from `Homebrew`_ or `MacPorts`_. 238Cryptography does **not** support Apple's deprecated OpenSSL distribution. 239 240To build cryptography and dynamically link it: 241 242`Homebrew`_ 243 244.. code-block:: console 245 246 $ brew install openssl@1.1 247 $ env LDFLAGS="-L$(brew --prefix openssl@1.1)/lib" CFLAGS="-I$(brew --prefix openssl@1.1)/include" pip install cryptography 248 249`MacPorts`_: 250 251.. code-block:: console 252 253 $ sudo port install openssl 254 $ env LDFLAGS="-L/opt/local/lib" CFLAGS="-I/opt/local/include" pip install cryptography 255 256You can also build cryptography statically: 257 258`Homebrew`_ 259 260.. code-block:: console 261 262 $ brew install openssl@1.1 263 $ env CRYPTOGRAPHY_SUPPRESS_LINK_FLAGS=1 LDFLAGS="$(brew --prefix openssl@1.1)/lib/libssl.a $(brew --prefix openssl@1.1)/lib/libcrypto.a" CFLAGS="-I$(brew --prefix openssl@1.1)/include" pip install cryptography 264 265`MacPorts`_: 266 267.. code-block:: console 268 269 $ sudo port install openssl 270 $ env CRYPTOGRAPHY_SUPPRESS_LINK_FLAGS=1 LDFLAGS="/opt/local/lib/libssl.a /opt/local/lib/libcrypto.a" CFLAGS="-I/opt/local/include" pip install cryptography 271 272If you need to rebuild ``cryptography`` for any reason be sure to clear the 273local `wheel cache`_. 274 275 276.. _`Homebrew`: https://brew.sh 277.. _`MacPorts`: https://www.macports.org 278.. _`a binary distribution`: https://wiki.openssl.org/index.php/Binaries 279.. _virtualenv: https://virtualenv.pypa.io/en/latest/ 280.. _openssl.org: https://www.openssl.org/source/ 281.. _`wheel cache`: https://pip.pypa.io/en/stable/reference/pip_install/#caching 282