**********************************************************************
Installation
**********************************************************************

.. contents:: Contents
   :local:


Quick install
=============

Install pygit2:

.. code-block:: sh

   pip install -U pip
   pip install pygit2

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

.. note::

   It is recommended to first update the version of pip, as it will increase
   the chances for it to install a binary wheel instead of the source
   distribution. At least version 19.3 of pip is required.

If you get the error::

    fatal error: git2.h: No such file or directory

It means that pip did not find a binary wheel for your platform, so it tried to
build from source. It failed to build because it could not find the libgit2 headers.
Then:

- Verify pip is updated
- Verify there is a binary wheel of pygit2 for your platform
- Otherwise `install from the source distribution`_

Caveats:

- Binary wheels for Windows are available, but they don't have support for ssh.


Requirements
============

Supported versions of Python:

- Python 3.11 to 3.14
- PyPy3 7.3+

Python requirements (these are specified in ``setup.py``):

- cffi 2.0 or later

Libgit2 **v1.9.x**; binary wheels already include libgit2, so you only need to
worry about this if you `install from the source distribution`_.

Optional libgit2 dependencies to support ssh and https:

- https: WinHTTP (Windows), SecureTransport (OS X) or OpenSSL.
- ssh: libssh2 1.10.0 or later, pkg-config

To run the tests:

- pytest

Version numbers
===============

The version number of pygit2 is composed of three numbers separated by dots::

   <major>.<medium>.<minor>

- *major* will always be 1 (until we release 2.0 in a far undefined future)
- *medium* will increase whenever we make breaking changes, or upgrade to new
  versions of libgit2.
- *minor* will increase for bug fixes.

The table below summarizes the latest pygit2 versions with the supported versions
of Python and the required libgit2 version.

+-------------+----------------+------------+
| pygit2      | Python         | libgit2    |
+-------------+----------------+------------+
| 1.19        | 3.11 - 3.14(t) | 1.9        |
+-------------+----------------+------------+
| 1.17 - 1.18 | 3.10 - 3.13    | 1.9        |
+-------------+----------------+------------+
| 1.16        | 3.10 - 3.13    | 1.8        |
+-------------+----------------+------------+
| 1.15        | 3.9 - 3.12     | 1.8        |
+-------------+----------------+------------+
| 1.14        | 3.9 - 3.12     | 1.7        |
+-------------+----------------+------------+
| 1.13        | 3.8 - 3.12     | 1.7        |
+-------------+----------------+------------+
| 1.12        | 3.8 - 3.11     | 1.6        |
+-------------+----------------+------------+
| 1.11        | 3.8 - 3.11     | 1.5        |
+-------------+----------------+------------+
| 1.10        | 3.7 - 3.10     | 1.5        |
+-------------+----------------+------------+
| 1.9         | 3.7 - 3.10     | 1.4        |
+-------------+----------------+------------+
| 1.7 - 1.8   | 3.7 - 3.10     | 1.3        |
+-------------+----------------+------------+
| 1.4 - 1.6   | 3.6 - 3.9      | 1.1        |
+-------------+----------------+------------+
| 1.2 - 1.3   | 3.6 - 3.8      | 1.0        |
+-------------+----------------+------------+
| 1.1         | 3.5 - 3.8      | 0.99 - 1.0 |
+-------------+----------------+------------+
| 1.0         | 3.5 - 3.8      | 0.28       |
+-------------+----------------+------------+
| 0.28.2      | 2.7, 3.4 - 3.7 | 0.28       |
+-------------+----------------+------------+

.. warning::

   It is recommended to use the latest 1.x.y release. Because only the latest
   is supported.

.. warning::

   Backwards compatibility is not guaranteed in minor releases. Please check
   the release notes for incompatible changes before upgrading to a new
   release.

.. warning::

   Threaded builds are experimental, do not use them in production.

History: the 0.x series
-----------------------

The development of pygit2 started in October 2010, the release of 1.0.0
happened in December 2019. In the 0.x series the version numbering was
lockstep with libgit2, e.g. pygit2 0.28.x worked with libgit2 0.28.x


Advanced
===========================

.. _install from the source distribution:

Install libgit2 from source
---------------------------

Installing from source requires

* a C compiler (such as gcc)
* the CPython API headers (typically in an ``apt`` package named ``python3-dev``)

To install the latest version of libgit2 system wide, in the ``/usr/local``
directory, do:

.. code-block:: sh
   :caption: On Linux using bash

   wget https://github.com/libgit2/libgit2/archive/refs/tags/v1.9.2.tar.gz -O libgit2-1.9.2.tar.gz
   tar -xzf libgit2-1.9.2.tar.gz
   cd libgit2-1.9.2/
   cmake .
   make
   sudo make install

.. seealso::

   For detailed instructions on building libgit2 check
   https://libgit2.org/docs/guides/build-and-link/

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

.. code-block:: sh

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


Troubleshooting
---------------------------

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

.. code-block:: text

   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 within
the ``/usr/local/lib`` directory, but the linker does not look for it there. To
fix this call ``ldconfig``:

.. code-block:: sh
   :caption: On Linux using bash

   sudo ldconfig
   python -c 'import pygit2'

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


Build options
---------------------------

``LIBGIT2`` -- If you install libgit2 in an unusual place, you will need to set
the ``LIBGIT2`` environment variable before installing pygit2.  This variable
tells 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 to
override the library directory where libgit2 is installed, useful if different
from ``$LIBGIT2/lib`` and ``$LIBGIT2/lib64``.


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 access to install libgit2 system wide.
Or if you wish to have different versions of libgit2/pygit2 installed in
different virtual environments, isolated from each other.

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

.. code-block:: sh
   :caption: On Linux using bash

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

Install libgit2 (see we define the installation prefix):

.. code-block:: sh
   :caption: On Linux using bash

   wget https://github.com/libgit2/libgit2/archive/refs/tags/v1.9.2.tar.gz -O libgit2-1.9.2.tar.gz
   tar xzf libgit2-1.9.2.tar.gz
   cd libgit2-1.9.2/
   cmake . -DCMAKE_INSTALL_PREFIX=$LIBGIT2
   cmake --build . --target install

Install pygit2:

.. code-block:: sh
   :caption: On Linux using bash

   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 <http://en.wikipedia.org/wiki/Rpath>`_ before
installing pygit2?  Since libgit2 is installed in a non standard location, the
dynamic linker will not find it at run-time, and ``lddconfig`` will not help
this time.

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

.. code-block:: sh
   :caption: On Linux using bash

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

Or, like we have done in the instructions above, use the `rpath
<http://en.wikipedia.org/wiki/Rpath>`_, it hard-codes extra search paths within
the pygit2 extension modules, so you don't need to set ``LD_LIBRARY_PATH``
every time. Verify yourself if curious:

.. code-block:: sh
   :caption: On Linux using bash

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


Installing on Windows
===================================

``pygit2`` for Windows is packaged into wheels and can be easily installed with
``pip``:

.. code-block:: console

   pip install pygit2

For development it is also possible to build ``pygit2`` with ``libgit2`` from
sources. ``libgit2`` location is specified by the ``LIBGIT2`` environment
variable.  The following recipe shows you how to do it:

.. code-block:: pwsh
   :caption: On Windows using PowerShell (and CMake v3.21 or newer)

   git clone --depth=1 -b v1.9.2 https://github.com/libgit2/libgit2.git
   $env:CMAKE_INSTALL_PREFIX = "C:/Dev/libgit2"
   $env:CMAKE_GENERATOR = "Visual Studio 17 2022"
   $env:CMAKE_GENERATOR_PLATFORM = "x64" # or "Win32" or "ARM64"
   cmake -B libgit2/build -S libgit2
   cmake --build libgit2/build --config release --target install

   # let pip know where to find libgit2 when building pygit2
   $env:LIBGIT2 = "$env:CMAKE_INSTALL_PREFIX"

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 the
source package.

.. note::

   You will need the `XCode <https://developer.apple.com/xcode/>`_ Developer
   Tools from Apple. This free download from the Mac App Store will provide the
   clang compiler needed for the installation of pygit2.

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

The easiest way is to first install libgit2 with the `Homebrew <http://brew.sh>`_
package manager and then use pip3 for pygit2. The following example assumes that
XCode and Homebrew are already installed.

.. code-block:: sh

   brew update
   brew install libgit2
   pip3 install pygit2

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