Installation

Quick install

Install pygit2:

$ pip install pygit2

The line above will install binary wheels if available in your platform.

To install the source package:

$ pip install pygit2 --no-binary

It’s preferable to install the source package, if it works for you. But thebinary package will often be easier to install.

Requirements

Supported versions of Python:

• Python 2.7 and 3.4+

• PyPy 2.7 and 3.5
  Python requirements (these are specified in setup.py):

• cffi 1.0+

• six
  Libgit2 v0.28.x (see the version numbering section below for details).Binary wheels already include libgit2, so you only need to worry about this ifyou install the source package

Optional libgit2 dependecies to support ssh and https:

• https: WinHTTP (Windows), SecureTransport (OS X) or OpenSSL.

• ssh: libssh2, pkg-config
  To run the tests:

• pytest

• tox (optional)

Version numbers

Warning

One common mistake users do is to choose incompatible versions of libgit2and pygit2. Double check the versions do match before filing a bug report.Though you don’t need to worry about this if you install a binary wheel.

The version number 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.

It is recommended to use the latest version in each series. Example ofcompatible releases:

Warning

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

Advanced

Install libgit2 from source

To install the latest version of libgit2 system wide, in the /usr/localdirectory, do:

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

See also

For detailed instructions on building libgit2 checkhttps://libgit2.github.com/docs/guides/build-and-link/

Now install pygit2, and then verify it is correctly installed:

$ pip install pygit2
...
$ python -c 'import pygit2'

Troubleshooting

The verification step may fail if the dynamic linker does not find the libgit2library:

$ 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

This happens for instance in Ubuntu, the libgit2 library is installed withinthe /usr/local/lib directory, but the linker does not look for it there. Tofix this call ldconfig:

$ sudo ldconfig
$ python -c 'import pygit2'

If it still does not work, please open an issue athttps://github.com/libgit2/pygit2/issues

Build options

LIBGIT2 – If you install libgit2 in an unusual place, you will need to setthe LIBGIT2 environment variable before installing pygit2. This variabletells pygit2 where libgit2 is installed. We will see a concrete example later,when explaining how to install libgit2 within a virtual environment.

LIBGIT2_LIB – This is a more rarely used build option, it allows tooverride the library directory where libgit2 is installed, useful if differentfrom $LIBGIT2/lib.

libgit2 within a virtual environment

This is how to install both libgit2 and pygit2 within a virtual environment.

This is useful if you don’t have root acces to install libgit2 system wide.Or if you wish to have different versions of libgit2/pygit2 installed indifferent virtual environments, isolated from each other.

Create the virtualenv, activate it, and set the LIBGIT2 environmentvariable:

$ 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.28.2.tar.gz
$ tar xzf v0.28.2.tar.gz
$ cd libgit2-0.28.2/
$ cmake . -DCMAKE_INSTALL_PREFIX=$LIBGIT2
$ make
$ make install

Install pygit2:

$ export LDFLAGS="-Wl,-rpath='$LIBGIT2/lib',--enable-new-dtags $LDFLAGS"
# on OSX: export LDFLAGS="-Wl,-rpath,'$LIBGIT2/lib' $LDFLAGS"
$ pip install pygit2
$ python -c 'import pygit2'

The run-path

Did you notice we set the rpath beforeinstalling pygit2? Since libgit2 is installed in a non standard location, thedynamic linker will not find it at run-time, and lddconfig will not helpthis time.

So you need to either set LD_LIBRARY_PATH before using pygit2, like:

$ export LD_LIBRARY_PATH=$LIBGIT2/lib
$ python -c 'import pygit2'

Or, like we have done in the instructions above, use the rpath, it hard-codes extra search paths withinthe pygit2 extension modules, so you don’t need to set LD_LIBRARY_PATHeverytime. Verify yourself if curious:

$ readelf --dynamic lib/python2.7/site-packages/pygit2-0.27.0-py2.7-linux-x86_64.egg/_pygit2.so | grep PATH
 0x000000000000001d (RUNPATH)            Library runpath: [/tmp/venv/lib]

Installing on Windows

pygit2 for Windows is packaged into wheels and can be easilyinstalled with pip:

pip install pygit2

For development it is also possible to build pygit2 with libgit2 fromsources. libgit2 location is specified by the LIBGIT2 environmentvariable. The following recipe shows you how to do it from a bash shell:

$ export LIBGIT2=C:/Dev/libgit2
$ git clone --depth=1 -b maint/v0.26 https://github.com/libgit2/libgit2.git
$ cd libgit2
$ cmake . -DCMAKE_INSTALL_PREFIX=$LIBGIT2 -G "Visual Studio 14 Win64"
$ cmake --build . --config release --target install
$ ctest -v

At this point, you’re ready to execute the generic _pygit2_installation steps described at the start of this page.

Installing on OS X

There are not binary wheels available for OS X, so you will need to install thesource package.

Note

You will need the XCode DeveloperTools from Apple. This free download from the Mac App Store will provide theclang compiler needed for the installation of pygit2.

This section was tested on OS X 10.9 Mavericks and OS X 10.10 Yosemite withPython 3.3 in a virtual environment.

The easiest way is to first install libgit2 with the Homebrewpackage manager and then use pip3 for pygit2. The following example assumes thatXCode and Hombrew are already installed.

$ brew update
$ brew install libgit2
$ pip3 install pygit2

To build from a non-Homebrew libgit2 follow the guide in libgit2 within a virtual environment.