1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
|
==========
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
===============
The recommended way to get Paramiko is to **install the latest stable release**
via `pip <http://pip-installer.org>`_::
$ pip install paramiko
We currently support **Python 2.7, 3.4+, and PyPy**. Users on Python 2.6 or
older (or 3.3 or older) are urged to upgrade.
Paramiko has only a few **direct dependencies**:
- The big one, with its own sub-dependencies, is Cryptography; see :ref:`its
specific note below <cryptography>` for more details;
- `bcrypt <https://pypi.org/project/bcrypt/>`_, for Ed25519 key support;
- `pynacl <https://pypi.org/project/PyNaCl/>`_, also for Ed25519 key support.
There are also a number of **optional dependencies** you may install using
`setuptools 'extras'
<https://packaging.python.org/tutorials/installing-packages/#installing-setuptools-extras>`_:
.. TODO 3.0: tweak the invoke line to mention proxycommand too
.. TODO 3.0: tweak the ed25519 line to remove the caveat
- If you want all optional dependencies at once, use ``paramiko[all]``.
- For ``Match exec`` config support, use ``paramiko[invoke]`` (which installs
`Invoke <https://www.pyinvoke.org>`_).
- For GSS-API / SSPI support, use ``paramiko[gssapi]``, though also see
:ref:`the below subsection on it <gssapi>` for details.
- ``paramiko[ed25519]`` references the dependencies for Ed25519 key support.
- As of Paramiko 2.x this doesn't technically do anything, as those
dependencies are core installation requirements.
- However, you should use this for forwards compatibility; 3.0 will drop
those dependencies from core, leaving them purely optional.
.. _release-lines:
Release lines
-------------
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.
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. 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. 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.
.. 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.
* Similarly, Cryptography 3.4 and above require Rust language tooling to
install from source; once again see Cryptography's documentation for details
here, such as `their Rust install section`_ and `this FAQ entry`_.
.. _installation instructions:
.. _Cryptography's install docs: https://cryptography.io/en/latest/installation.html
.. _their Rust install section: https://cryptography.io/en/latest/installation.html#rust
.. _this FAQ entry: https://cryptography.io/en/latest/faq.html#installing-cryptography-fails-with-error-can-not-find-rust-compiler
.. _gssapi:
Optional dependencies for GSS-API / SSPI / Kerberos
===================================================
In order to use GSS-API/Kerberos & related functionality, additional
dependencies are required. It hopefully goes without saying but **all
platforms** need **a working installation of GSS-API itself**, e.g. Heimdal.
.. note::
If you use Microsoft SSPI for kerberos authentication and credential
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
The ``gssapi`` "extra" install flavor
-------------------------------------
If you're installing via ``pip`` (recommended), you should be able to get the
optional Python package requirements by changing your installation to refer to
``paramiko[gssapi]`` (from simply ``paramiko``), e.g.::
pip install "paramiko[gssapi]"
(Or update your ``requirements.txt``, or etc.)
.. TODO: just axe this once legacy gssapi support is gone, no point reiterating
Manual dependency installation
------------------------------
If you're not using ``pip`` or your ``pip`` is too old to support the "extras"
functionality, the optional dependencies are as follows:
* All platforms need `pyasn1 <https://pypi.org/project/pyasn1/>`_ ``0.1.7`` or
later.
* **Unix** needs: `gssapi <https://pypi.org/project/gssapi/>`__ ``1.4.1`` or better.
* An alternative is the `python-gssapi
<https://pypi.org/project/python-gssapi/>`_ library (``0.6.1`` or above),
though it is no longer maintained upstream, and Paramiko's support for
its API may eventually become deprecated.
* **Windows** needs `pywin32 <https://pypi.python.org/pypi/pywin32>`_ ``2.1.8``
or better.
|
