Installing ansible-pylibssh

This page describes how to install ansible-pylibssh using pip. Consult with pip docs if you are not sure whether you have it set up.

Pre-compiled binary distributions

ansible-pylibssh contains Cython-based CPython C-extension modules. Unlike pure-Python modules, these must be pre-compiled before consumption.

We publish platform-specific wheels to PyPI. They are built against different arch, CPython and OS versions so in 99% of cases, you may seamlessly install ansible-pylibssh not needing any external dependencies on your system.

It should be enough for you to just have Python 3.6+ and a recent pip installed.


Please make sure you have the latest version of pip before installing ansible-pylibssh.

If you have a version of pip older than 8.1, it’ll be unable to pick up OS-specific Python package distributions from PyPI and will try to fall back to building it from source which would require more extra dependencies to succeed. You can upgrade by following pip’s upgrade instructions.

To install ansible-pylibssh, just run:

$ pip install --user ansible-pylibssh


Avoid running pip with sudo as this will make global changes to the system. Since pip does not coordinate with system package managers, it could make changes to your system that leaves it in an inconsistent or non-functioning state. This is particularly true for macOS. Installing with --user is recommended unless you understand fully the implications of modifying global files on the system.

Installing ansible-pylibssh from source distribution (PyPI)

Installing ansible-pylibssh from source is a bit more complicated. First, pylibssh requires libssh to be compiled against, in particular, version 0.9.0 or newer. Please refer to libssh Downloads page for more information about installing it. Make sure that you have the development headers too.

Another essential build dependency is GCC. You may already have it installed but if not, consult with your OS docs.

Once you have the build prerequisites, the following command should download the tarball, build it and then install into your current env:

$ pip install \
    --user \
    --no-binary ansible-pylibssh \


When your copy of libssh-dev is installed into a non-default directory, make sure to prepend the compiler environment variables (e.g CFLAGS=-I/usr/local/include) right before the pip install command. For the macOS users who install it using Homebrew, it should be enough to set CFLAGS="-I $(brew --prefix)/include -I ext -L $(brew --prefix)/lib -lssh"

Building ansible-pylibssh dists from the devel branch in Git

Since our build processes are tox-centric, let’s install it first:

$ python -m pip install 'tox >= 3.19.0' --user

Now, let’s grab the source of ansible-pylibssh:

$ git clone ~/src/github/ansible/pylibssh
$ # or, if you use SSH:
$ git clone ~/src/github/ansible/pylibssh
$ cd ~/src/github/ansible/pylibssh
[dir:pylibssh] $

Finally, you can build the dists for the current env using:

[dir:pylibssh] $ tox -e build-dists

If you want to generate the whole matrix of manylinux-compatible wheels, use:

[dir:pylibssh] $ tox -e build-dists-manylinux1-x86_64  # with Docker

[dir:pylibssh] $ # or with Podman
[dir:pylibssh] $ DOCKER_EXECUTABLE=podman tox -e build-dists-manylinux1-x86_64

See also

Getting Started with ansible-pylibssh

Examples of getting started

Continuous delivery

Using nightly builds to test your project against