diff options
Diffstat (limited to 'sites/www/installing.rst')
| -rw-r--r-- | sites/www/installing.rst | 78 |
1 files changed, 51 insertions, 27 deletions
diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 9f1f9080..5a41a76b 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -2,6 +2,13 @@ Installing ========== + +.. note:: + These instructions cover Paramiko 2.0 and above. If you're looking to + install Paramiko 1.x, see :doc:`installing-1.x`. However, **the 1.x line + relies on insecure dependencies** so upgrading is strongly encouraged. + + .. _paramiko-itself: Paramiko itself @@ -16,14 +23,15 @@ via `pip <http://pip-installer.org>`_:: Users who want the bleeding edge can install the development version via ``pip install paramiko==dev``. -We currently support **Python 2.6, 2.7, 3.3+, and PyPy** Users on Python 2.5 or -older are urged to upgrade. +We currently support **Python 2.6, 2.7, 3.3+, and PyPy**. Users on Python 2.5 +or older (or 3.2 or older) are urged to upgrade. -Paramiko has two hard dependencies: the pure-Python ASN1 module ``pyasn1``, and -the Cryptography library. Read on for details on installing ``cryptography``. +Paramiko has only one direct hard dependency: the Cryptography library. See +:ref:`cryptography`. If you need GSS-API / SSPI support, see :ref:`the below subsection on it -<gssapi>` for details on additional dependencies. +<gssapi>` for details on its optional dependencies. + .. _release-lines: @@ -34,43 +42,53 @@ Users desiring stability may wish to pin themselves to a specific release line once they first start using Paramiko; to assist in this, we guarantee bugfixes for the last 2-3 releases including the latest stable one. -If you're unsure which version to install, we have suggestions: +This typically spans major & minor versions, so even if e.g. 3.1 is the latest +stable release, it's likely that bugfixes will occasionally come out for the +latest 2.x and perhaps even 1.x releases, as well as for 3.0. New feature +releases for previous major-version lines are less likely but not unheard of. + +If you're unsure which version to install: * **Completely new users** should always default to the **latest stable release** (as above, whatever is newest / whatever shows up with ``pip install paramiko``.) -* **Users upgrading from a much older version** (e.g. the 1.7.x line) should - probably get the **oldest actively supported line** (see the paragraph above - this list for what that currently is.) +* **Users upgrading from a much older version** (e.g. 1.7.x through 1.10.x) + should probably get the **oldest actively supported line** (check the + :doc:`changelog` for recent releases). * **Everybody else** is hopefully already "on" a given version and can carefully upgrade to whichever version they care to, when their release line stops being supported. +.. _cryptography: + Cryptography ============ -`Cryptography <https://cryptography.io>`_ provides the low-level (C-based) -encryption algorithms we need to implement the SSH protocol. There are a few -things to be aware of when installing Cryptography, because it includes a -C-extension. +`Cryptography <https://cryptography.io>`__ provides the low-level (C-based) +encryption algorithms we need to implement the SSH protocol. It has detailed +`installation instructions`_ (and an `FAQ +<https://cryptography.io/en/latest/faq/>`_) which you should read carefully. + +In general, you'll need one of the following setups: + +* On Windows or Mac OS X, provided your ``pip`` is modern (8.x+): nothing else + is required. ``pip`` will install statically compiled binary archives of + Cryptography & its dependencies. +* On Linux, or on other platforms with older versions of ``pip``: you'll need a + C build toolchain, plus development headers for Python, OpenSSL and + ``libffi``. Again, see `Cryptography's install docs`_; these requirements may + occasionally change. -C extension ------------ + .. warning:: + If you go this route, note that **OpenSSL 1.0.1 or newer is effectively + required**. Cryptography 1.3 and older technically allow OpenSSL 0.9.8, but + 1.4 and newer - which Paramiko will gladly install or upgrade, if you e.g. + ``pip install -U`` - drop that support. -Unless you are installing from a precompiled source such as a Debian apt -repository or RedHat RPM, you will also need the ability to build Python -C-based modules from source in order to install Cryptography. Users on **Unix- -based platforms** such as Ubuntu or Mac OS X will need the traditional C build -toolchain installed (e.g. Developer Tools / XCode Tools on the Mac, or the -``build-essential`` package on Ubuntu or Debian Linux -- basically, anything -with ``gcc``, ``make`` and so forth) as well as the Python development -libraries, often named ``python-dev`` or similar, OpenSSL headers, often named -``libssl-dev``, and libffi development libraries, often named ``libffi-dev``. +.. _installation instructions: +.. _Cryptography's install docs: https://cryptography.io/en/latest/installation/ -For **Windows** users we recommend using the most recent version of ``pip``, -Cryptography has binary wheels on PyPI, which remove the need for having a C -compiler. .. _gssapi: @@ -96,3 +114,9 @@ due to their infrequent utility & non-platform-agnostic requirements): delegation, make sure that the target host is trusted for delegation in the active directory configuration. For details see: http://technet.microsoft.com/en-us/library/cc738491%28v=ws.10%29.aspx + + +.. toctree:: + :hidden: + + installing-1.x |