================================

===============================

.. _installing-pybind11:

Installing pybind11

--------------------

To install ``pybind11`` use pip

::

$ pip install pybind11

Or if you are using conda:

::

$ conda install pybind11

If you want to build ``pybind11`` yourself, you can install the dependencies and then run the following command in your source directory:

.. code-block:: bash

$ mkdir build && cd build && cmake .. && make -j$(nproc) && sudo make install

You can also use `conda env export` to create a conda environment with pybind11 and then use `conda env import` to recreate the same environment on a different machine. This will also take care of any dependencies that may have changed over time.

.. note::

``pybind11`` supports C++11 or higher. If you're using an older version of gcc, consider installing `gcc-7` which is known to work well with ``pybind11``: http://linuxcommand.org/lc3_software/How_to_Install_the_C_Compiler_GCC

.. note::

If you're using a different compiler, you can set it manually by passing the ``-DCMAKE_CXX_COMPILER=`` flag when running ``cmake``.

For example, if you have `gcc-7` installed in your system and you want to use that, you'd run:

.. code-block:: bash

$ cmake -DCMAKE_CXX_COMPILER=/usr/bin/g++-7 ..

Building pybind11 with python3.6 or higher

------------------------------------------

Since python3.6, ``pybind11`` now uses the `pybind11::embedded` module for building its embedded interpreter. This is a big change and requires some changes to the build system of ``pybind11``.

To compile ``pybind11`` with ``python3.6`` or higher, you need to follow these steps:

1. Clone pybind11 from `github.com/pybind/pybind11`_ and navigate into the source directory.

2. Create a subdirectory named ``build``, run ``cd build``, and then call ``cmake`` with the appropriate flags.

3. Compile ``pybind11`` with ``make -j$(nproc)`` (or use ``-j`` for building with fewer threads).

4. Install ``pybind11`` with ``sudo make install``.

.. note::

If you're using a different compiler, you can set it manually by passing the ``-DCMAKE_CXX_COMPILER=`` flag when running ``cmake``.

For example, if you have `gcc-7` installed in your system and you want to use that, you'd run:

.. code-block:: bash

$ cmake -DCMAKE_CXX_COMPILER=/usr/bin/g++-7 ..

.. warning::

The above build instructions assume that you have the appropriate version of python3.6 installed on your system and it is located at ``/usr/local/bin/python3.6``. If this is not the case, please update the path appropriately in the ``CMakeLists.txt`` file.

Also, make sure you have ``libffi-dev`` installed.

.. note::

If you're using Ubuntu or Debian, the above instructions will not work because the ``pybind11`` source code does not include the necessary files to build with Ubuntu/Debian. Instead, you can use the following commands:

.. code-block:: bash

$ cd /opt/python3.6/include/python3.6/

$ python3 -m ensurepip --default-pip

$ python3 -m pip install pybind11

Building pybind11 with python2.7 or higher

------------------------------------------

To compile ``pybind11`` with ``python2.7`` or higher, you need to follow these steps:

1. Clone pybind11 from `github.com/pybind/pybind11`_ and navigate into the source directory.

2. Create a subdirectory named ``build``, run ``cd build``, and then call ``cmake`` with the appropriate flags.

3. Compile ``pybind11`` with ``make -j$(nproc)`` (or use ``-j`` for building with fewer threads).

4. Install ``pybind11`` with ``sudo make install``.

.. note::

If you're using a different compiler, you can set it manually by passing the ``-DCMAKE_CXX_COMPILER=`` flag when running ``cmake``.

For example, if you have `gcc-7` installed in your system and you want to use that, you'd run:

.. code-block:: bash

$ cmake -DCMAKE_CXX_COMPILER=/usr/bin/g++-7 ..

.. note::

If you're using Ubuntu or Debian, the above instructions will not work because the ``pybind11`` source code does not include the necessary files to build with Ubuntu/Debian. Instead, you can use the following commands:

.. code-block:: bash

$ cd /opt/python2.7/include/python2.7/

$ python -m ensurepip --default-pip

$ python -m pip install pybind11

.. note::

If you're using python2.7, make sure to also install ``libffi-dev``:

.. code-block:: bash

$ sudo apt-get install libffi-dev

Building with gcc6 and older versions of python

-----------------------------------------------

Python 3.4+ uses the GCC6 compiler by default. However, if you need to build ``pybind11`` with an older version of gcc (e.g., GCC5), you can set the ``CMAKE_CXX_COMPILER`` flag when calling cmake:

.. code-block:: bash

$ mkdir build && cd build && cmake -DCMAKE_CXX_COMPILER=/usr/bin/g++-5 ..

If you're using python2.7 and you want to use an older version of gcc, make sure to also install the necessary dependencies for that version of gcc (e.g., ``libffi-dev``).