deb-python-pygit2/docs/install.rst

Installation

Contents

Requirements

• Python 2.7, 3.2, 3.3, 3.4 or pypy. Including the development headers.
• Libgit2 v0.21.1
• cffi 0.8.1+

One common mistake users do is to choose incompatible versions of libgit2 and pygit2. Be sure to use the latest release of both, double check the versions do match before filling un bug report.

Note

The version of pygit2 is composed of three numbers separated by dots « major.minor.micro », where the first two numbers « major.minor » match the first two numbers of the libgit2 version, while the last number « .micro » auto-increments independently.

As illustration see this table of compatible releases:

libgit2	0.21.1	0.20.0
pygit2	0.21.0, 0.21.1, 0.21.2	0.20.0, 0.20.1, 0.20.2, 0.20.3

Warning! Backwards compatibility is not guaranteed even between micro releases. Please check the release notes for incompatible changes before upgrading to a new release.

Quick install

This works for me, it may work for you:

$ wget https://github.com/libgit2/libgit2/archive/v0.21.1.tar.gz
$ tar xzf v0.21.1.tar.gz
$ cd libgit2-0.21.1/
$ cmake .
$ make
$ sudo make install

If this does not work for you, check the detailed instructions on building libgit2 in various platforms, see https://libgit2.github.com/docs/guides/build-and-link/

Once libgit2 is instaleld, deploying pygit2 should be a snap:

$ pìp install cffi
$ pip install pygit2

Troobleshooting

You may get an error like this one:

$ python -c 'import pygit2'
Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File "pygit2/__init__.py", line 29, in <module>
    from _pygit2 import *
ImportError: libgit2.so.0: cannot open shared object file: No such file or directory

It means the linker is not able to find the libgit2 library.

This happens for instance in Ubuntu: the libgit2 library is installed within the /usr/local/lib directory, but the linker does not look for it there. To fix this call ldconfig between the installation of libgit2 and the installation of pygit2:

...
$ cmake .
$ make
$ sudo make install
...
$ sudo ldconfig
...
$ pip install cffi
$ pip install pygit2

Now it should work. If it does not...

Advanced: the runpath

If it does not work yet, you can always instruct pygit2 to search for libraries in some extra paths:

$ export LIBGIT2="/usr/local"
$ export LDFLAGS="-Wl,-rpath='$LIBGIT2/lib',--enable-new-dtags $LDFLAGS"
$ pip install pygit2

This compiles the pygit2 libraries with a RUNPATH, which bakes extra library search paths directly into the binaries (see the ld man page for details). With RUNPATH compiled in, you won't have to use LD_LIBRARY_PATH. You can check to ensure RUNPATH was set with readelf:

$ readelf --dynamic build/lib.linux-x86_64-3.2/_pygit2.cpython-32.so | grep PATH
0x000000000000000f (RPATH)              Library rpath: [/usr/local/lib]
0x000000000000001d (RUNPATH)            Library runpath: [/usr/local/lib]

The LIBGIT2 environment variable

If libgit2 is installed in some non standard location, you will have to set the LIBGIT2 environment variable before installing pygit2. This variables tells pygit2 where libgit2 is installed.

Use case: libgit2 within a Virtualenv

A use case for this is if you want to install libgit2 inside a virtualenv, so you may have several virtualenvs with different versions of libgit2/pygit2, isolated from each other. Or maybe you just don't have root access to install libgit2 in the system.

Create the virtualenv, activate it, and set the LIBGIT2 environment variable:

$ virtualenv venv
$ source venv/bin/activate
$ export LIBGIT2=$VIRTUAL_ENV

Install libgit2 (see we define the installation prefix):

$ wget https://github.com/libgit2/libgit2/archive/v0.21.1.tar.gz
$ tar xzf v0.21.1.tar.gz
$ cd libgit2-0.21.1/
$ cmake . -DCMAKE_INSTALL_PREFIX=$LIBGIT2
$ make
$ make install

Install pygit2:

$ pìp install cffi
$ pip install pygit2

Building on Windows

pygit2 expects to find the libgit2 installed files in the directory specified in the LIBGIT2 environment variable.

In addition, make sure that libgit2 is build in "__cdecl" mode. The following recipe shows you how to do it, assuming you're working from a bash shell:

$ export LIBGIT2=C:/Dev/libgit2
$ wget https://github.com/libgit2/libgit2/archive/v0.21.1.tar.gz
$ tar xzf v0.21.1.tar.gz
$ cd libgit2-0.21.1/
$ mkdir build
$ cd build
$ cmake .. -DSTDCALL=OFF -DCMAKE_INSTALL_PREFIX=$LIBGIT2 -G "Visual Studio 9 2008"
$ cmake --build . --config release --target install
$ ctest -v

At this point, you're ready to execute the generic pygit2 installation steps described above.