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

.. _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=<path_to_your_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<num_threads>`` 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=<path_to_your_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<num_threads>`` 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=<path_to_your_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``).