1.. _installing: 2 3Installing the library 4###################### 5 6There are several ways to get the pybind11 source, which lives at 7`pybind/pybind11 on GitHub <https://github.com/pybind/pybind11>`_. The pybind11 8developers recommend one of the first three ways listed here, submodule, PyPI, 9or conda-forge, for obtaining pybind11. 10 11.. _include_as_a_submodule: 12 13Include as a submodule 14====================== 15 16When you are working on a project in Git, you can use the pybind11 repository 17as a submodule. From your git repository, use: 18 19.. code-block:: bash 20 21 git submodule add -b stable ../../pybind/pybind11 extern/pybind11 22 git submodule update --init 23 24This assumes you are placing your dependencies in ``extern/``, and that you are 25using GitHub; if you are not using GitHub, use the full https or ssh URL 26instead of the relative URL ``../../pybind/pybind11`` above. Some other servers 27also require the ``.git`` extension (GitHub does not). 28 29From here, you can now include ``extern/pybind11/include``, or you can use 30the various integration tools (see :ref:`compiling`) pybind11 provides directly 31from the local folder. 32 33Include with PyPI 34================= 35 36You can download the sources and CMake files as a Python package from PyPI 37using Pip. Just use: 38 39.. code-block:: bash 40 41 pip install pybind11 42 43This will provide pybind11 in a standard Python package format. If you want 44pybind11 available directly in your environment root, you can use: 45 46.. code-block:: bash 47 48 pip install "pybind11[global]" 49 50This is not recommended if you are installing with your system Python, as it 51will add files to ``/usr/local/include/pybind11`` and 52``/usr/local/share/cmake/pybind11``, so unless that is what you want, it is 53recommended only for use in virtual environments or your ``pyproject.toml`` 54file (see :ref:`compiling`). 55 56Include with conda-forge 57======================== 58 59You can use pybind11 with conda packaging via `conda-forge 60<https://github.com/conda-forge/pybind11-feedstock>`_: 61 62.. code-block:: bash 63 64 conda install -c conda-forge pybind11 65 66 67Include with vcpkg 68================== 69You can download and install pybind11 using the Microsoft `vcpkg 70<https://github.com/Microsoft/vcpkg/>`_ dependency manager: 71 72.. code-block:: bash 73 74 git clone https://github.com/Microsoft/vcpkg.git 75 cd vcpkg 76 ./bootstrap-vcpkg.sh 77 ./vcpkg integrate install 78 vcpkg install pybind11 79 80The pybind11 port in vcpkg is kept up to date by Microsoft team members and 81community contributors. If the version is out of date, please `create an issue 82or pull request <https://github.com/Microsoft/vcpkg/>`_ on the vcpkg 83repository. 84 85Global install with brew 86======================== 87 88The brew package manager (Homebrew on macOS, or Linuxbrew on Linux) has a 89`pybind11 package 90<https://github.com/Homebrew/homebrew-core/blob/master/Formula/pybind11.rb>`_. 91To install: 92 93.. code-block:: bash 94 95 brew install pybind11 96 97.. We should list Conan, and possibly a few other C++ package managers (hunter, 98.. perhaps). Conan has a very clean CMake integration that would be good to show. 99 100Other options 101============= 102 103Other locations you can find pybind11 are `listed here 104<https://repology.org/project/python:pybind11/versions>`_; these are maintained 105by various packagers and the community. 106