.. _installation:

Installation
============

You can either download one of the pre-built binaries or build the source code
manually. Pre-built binaries and other resources can be downloaded from
https://demuc.de/colmap/.

An overview of system packages for Linux/Unix/BSD distributions are available at
https://repology.org/metapackage/colmap/versions. Note that the COLMAP packages
in the default repositories for Linux/Unix/BSD do not come with CUDA or HIP/ROCm
support, which requires a manual build from source, as explained further below.

For Mac users, `Homebrew <https://brew.sh>`__ provides a formula for COLMAP with
pre-compiled binaries or the option to build from source. After installing
homebrew, installing COLMAP is as easy as running ``brew install colmap``.

COLMAP can be used as an independent application through the command-line or
graphical user interface. Alternatively, COLMAP is also built as a reusable
library, i.e., you can include and link COLMAP against your own C++ source code,
as described further below. Furthermore, you can use most of COLMAP's
functionality with :ref:`PyCOLMAP <pycolmap/index>` in Python.

------------------
Pre-built Binaries
------------------

Windows
-------

For convenience, the pre-built binaries for Windows contain both the graphical
and command-line interface executables. To start the COLMAP GUI, you can simply
double-click  the ``COLMAP.bat`` batch script or alternatively run it from the
Windows command shell or Powershell. The command-line interface is also
accessible through this batch script, which automatically sets the necessary
library paths. To list the available COLMAP commands, run ``COLMAP.bat -h`` in
the command shell ``cmd.exe`` or in Powershell. The first time you run COLMAP,
Windows defender may prompt you with a security warning, because the binaries
are not officially signed. The provided COLMAP binaries are automatically built
from GitHub Actions CI machines. If you do not trust them, you can build from
source as described below.

Docker
------

COLMAP provides a pre-built Docker image with CUDA support. For detailed
instructions on how to build and run COLMAP using Docker, please refer to the
`Docker documentation <https://github.com/colmap/colmap/tree/main/docker>`__.

-----------------
Build from Source
-----------------

COLMAP builds on all major platforms (Linux, Mac, Windows) with little effort.
First, checkout the latest source code::

    git clone https://github.com/colmap/colmap

Under Linux and Mac, it is generally recommended to follow the installation
instructions below, which use the respective system package managers to install
the required dependencies. Alternatively, the instructions for VCPKG can be used
to compile the required dependencies from scratch on more exotic systems with
limited system packages. The VCPKG approach is also the method of choice under
Windows, compute clusters, or if you do not have root access under Linux or Mac.


Debian/Ubuntu
-------------

*Recommended dependencies:* CUDA (at least version 11.X)

Dependencies from the default Ubuntu repositories::

    sudo apt-get install \
        git \
        cmake \
        ninja-build \
        build-essential \
        libboost-program-options-dev \
        libboost-graph-dev \
        libboost-system-dev \
        libeigen3-dev \
        libopenimageio-dev \
        openimageio-tools \
        libmetis-dev \
        libgoogle-glog-dev \
        libgtest-dev \
        libgmock-dev \
        libsqlite3-dev \
        libglew-dev \
        qt6-base-dev \
        libqt6opengl6-dev \
        libqt6openglwidgets6 \
        qt6-svg-dev \
        libcgal-dev \
        libceres-dev \
        libsuitesparse-dev \
        libcurl4-openssl-dev \
        libssl-dev \
        libmkl-full-dev
    # Fix issue in Ubuntu's openimageio CMake config.
    # We don't depend on any of openimageio's OpenCV functionality,
    # but it still requires the OpenCV include directory to exist.
    sudo mkdir -p /usr/include/opencv4

Alternatively, you can also build against Qt 5 instead of Qt 6 using::

    qtbase5-dev libqt5opengl5-dev libqt5svg5-dev

To compile with **CUDA support**, also install Ubuntu's default CUDA package::

    sudo apt-get install -y \
        nvidia-cuda-toolkit \
        nvidia-cuda-toolkit-gcc

Or, manually install the latest CUDA from NVIDIA's homepage. During CMake
configuration, specify ``-DCMAKE_CUDA_ARCHITECTURES=native``, if you want to run
COLMAP only on your current machine (default), "all"/"all-major" to be able to
distribute to other machines, or a specific CUDA architecture like "75", etc.

To compile with **HIP / ROCm support** instead of CUDA (for AMD GPUs), install
ROCm following the `AMD ROCm installation guide
<https://rocm.docs.amd.com/projects/install-on-linux/en/latest/>`__ and ensure
the ``hip``, ``hiprand``, and ``rocrand`` packages are present (default
location ``/opt/rocm``). Then pass the following flags at configure time::

    cmake .. -GNinja \
        -DCUDA_ENABLED=OFF \
        -DHIP_ENABLED=ON \
        -DCMAKE_HIP_ARCHITECTURES=gfx90a \
        -DCMAKE_HIP_COMPILER=/opt/rocm/llvm/bin/clang++

Set ``CMAKE_HIP_ARCHITECTURES`` to match the target AMD GPU
(``gfx90a`` for MI200/MI250, ``gfx942`` for MI300, ``gfx1030`` for RDNA2,
``gfx1100`` for RDNA3, etc.; multiple values can be passed as a
semicolon-separated list). ``CUDA_ENABLED`` and ``HIP_ENABLED`` are mutually
exclusive. CMake 3.21 or newer is required for the HIP backend. On RDNA3
consumer parts where ROCm only officially supports a subset of architectures,
you may also need ``HSA_OVERRIDE_GFX_VERSION=11.0.0`` in the runtime
environment. The HIP backend currently accelerates dense reconstruction
(``patch_match_stereo``); see the changelog for ongoing coverage.

If ROCm is installed through a Python wheel / virtualenv (for example AMD's
TheRock packaging, which puts a ``rocm-sdk`` command on the ``PATH``), the
install root and target architectures are detected automatically from
``rocm-sdk path --root`` and ``rocm-sdk targets``, so ``ROCM_PATH`` and
``CMAKE_HIP_ARCHITECTURES`` need not be set by hand. An explicit
``-DROCM_PATH`` or a ``ROCM_PATH`` environment variable still takes
precedence, and CMake's own architecture autodetection sets
``CMAKE_HIP_ARCHITECTURES`` when a target GPU is visible at configure time.

Configure and compile COLMAP::

    git clone https://github.com/colmap/colmap.git
    cd colmap
    mkdir build
    cd build
    cmake .. -GNinja -DBLA_VENDOR=Intel10_64lp
    ninja
    sudo ninja install

.. note::

    COLMAP can use ``boost::unordered`` flat/node hash maps for the
    performance-critical scene and SfM containers, selected via
    ``-DCOLMAP_HASH_MAP_BACKEND=BOOST|STD`` (default: auto). Auto selects
    ``BOOST`` when Boost is recent enough (``boost::unordered_node_map`` requires
    **Boost >= 1.84**) and falls back to ``STD`` (``std::unordered_map``)
    otherwise. Ubuntu's default Boost is older than 1.84, so apt-based builds use
    ``STD``; to use the faster ``BOOST`` backend, build against a newer Boost
    (e.g. via vcpkg, which installs ``boost-unordered`` automatically) or install
    Boost >= 1.84 manually. Explicitly requesting ``-DCOLMAP_HASH_MAP_BACKEND=BOOST``
    with an older Boost is a configuration error.

Run COLMAP::

    colmap -h
    colmap gui

Under **Ubuntu 22.04**, there is a problem when compiling with Ubuntu's default
CUDA package and GCC, and you must compile against GCC 10::

    sudo apt-get install gcc-10 g++-10
    export CC=/usr/bin/gcc-10
    export CXX=/usr/bin/g++-10
    export CUDAHOSTCXX=/usr/bin/g++-10
    # ... and then run CMake against COLMAP's sources.

Notice that the ``BLA_VENDOR=Intel10_64lp`` option tells CMake to find Intel's MKL
implementation of BLAS. If you decide to compile against OpenBLAS instead of
MKL, you must install and select the OpenMP version under Debian/Ubuntu because
of `this issue <https://github.com/facebookresearch/faiss/wiki/Troubleshooting#surprising-faiss-openmp-and-openblas-interaction>`__.

Fedora
------

*Recommended dependencies:* CUDA (at least version 11.X)

Dependencies from the default Fedora repositories::

    sudo dnf install -y \
        git \
        cmake \
        ninja-build \
        gcc-c++ \
        boost-devel \
        eigen3-devel \
        OpenImageIO-devel \
        OpenImageIO-utils \
        metis-devel \
        glog-devel \
        gtest-devel \
        gmock-devel \
        sqlite-devel \
        glew-devel \
        qt6-qtbase-devel \
        qt6-qtsvg-devel \
        CGAL-devel \
        ceres-solver-devel \
        suitesparse-devel \
        suitesparse-static \
        libcurl-devel \
        openssl-devel \
        openblas-devel
    # suitesparse-static is required even for a dynamic build, because Fedora's
    # SuiteSparse CMake config references the static targets file regardless of
    # link type. This can be dropped once Fedora ships SuiteSparse >= 7.11.0 with
    # its separated static config.

Alternatively, you can also build against Qt 5 instead of Qt 6 using::

    qt5-qtbase-devel qt5-qtsvg-devel

To compile with **CUDA support**, install the CUDA toolkit from NVIDIA's official
Fedora repository, which (unlike the plain ``cuda`` meta-package) preserves an
existing NVIDIA driver. Replace ``<VERSION>`` with your Fedora release, e.g.
``43``::

    sudo dnf config-manager addrepo --from-repofile=https://developer.download.nvidia.com/compute/cuda/repos/fedora<VERSION>/x86_64/cuda-fedora<VERSION>.repo
    sudo dnf install -y cuda-toolkit

During CMake configuration, specify ``-DCMAKE_CUDA_ARCHITECTURES=native``, if you
want to run COLMAP only on your current machine (default), "all"/"all-major" to be
able to distribute to other machines, or a specific CUDA architecture like "89", etc.

Configure and compile COLMAP::

    git clone https://github.com/colmap/colmap.git
    cd colmap
    mkdir build
    cd build
    cmake .. -GNinja -DCMAKE_CUDA_ARCHITECTURES=native
    ninja
    sudo ninja install

Run COLMAP::

    colmap -h
    colmap gui

Mac
---

Dependencies from `Homebrew <https://brew.sh/>`__::

    brew install \
        cmake \
        ninja \
        boost \
        eigen \
        openimageio \
        curl \
        libomp \
        metis \
        glog \
        googletest \
        ceres-solver \
        suitesparse \
        qt \
        glew \
        cgal \
        sqlite3
    brew link --force libomp

Configure and compile COLMAP::

    git clone https://github.com/colmap/colmap.git
    cd colmap
    mkdir build
    cd build
    cmake .. -GNinja
    ninja
    sudo ninja install

If you have Qt 5 installed on your system as well, you might have to temporarily
link your Qt 5 installation while configuring CMake::

    brew unlink qt && brew link --force qt
    cmake ...

Run COLMAP::

    colmap -h
    colmap gui


Windows
-------

*Recommended dependencies:* CUDA (at least version 11.X), Visual Studio 2019 or newer

On Windows, the recommended way is to build COLMAP using VCPKG::

    git clone https://github.com/microsoft/vcpkg
    cd vcpkg
    .\bootstrap-vcpkg.bat
    .\vcpkg install colmap[cuda,tests]:x64-windows

To compile CUDA for multiple compute architectures, please use::

    .\vcpkg install colmap[cuda-redist]:x64-windows

Please refer to the next section for more details.


VCPKG
-----

COLMAP ships as part of the VCPKG distribution. This enables to conveniently
build COLMAP and all of its dependencies from scratch under different platforms.
Note that VCPKG requires you to install CUDA manually in the standard way on
your platform. To compile COLMAP using VCPKG, you run::

    git clone https://github.com/microsoft/vcpkg
    cd vcpkg
    ./bootstrap-vcpkg.sh
    ./vcpkg install colmap:x64-linux

VCPKG ships with support for various other platforms (e.g., x64-osx,
x64-windows, etc.). To compile with CUDA support and to build all tests::

    ./vcpkg install colmap[cuda,tests]:x64-linux

The above commands will build the latest release version of COLMAP. To compile
the latest commit in the dev branch, you can use the following options::

    ./vcpkg install colmap:x64-linux --head

To modify the source code, you can further add ``--editable --no-downloads``.
Or, if you want to build from another folder and use the dependencies from
vcpkg, first run ``./vcpkg integrate install`` (under Windows use pwsh and
``./scripts/shell/enter_vs_dev_shell.ps1``) and then configure COLMAP as::

    cd path/to/colmap
    mkdir build
    cd build
    cmake .. -DCMAKE_TOOLCHAIN_FILE=path/to/vcpkg/scripts/buildsystems/vcpkg.cmake -DCMAKE_BUILD_TYPE=Release
    cmake --build . --config release --target colmap --parallel 24

Anaconda/Mamba
--------------

Install miniconda and run the following commands. You can replace ``conda`` with ``mamba`` for faster package installation::

    conda create -n colmap python=3.12
    conda config --add channels conda-forge
    conda config --set channel_priority strict
    conda install \
        cmake \
        ninja \
        boost \
        ccache \
        eigen \
        openimageio \
        curl \
        metis \
        glog \
        gtest \
        ceres-solver \
        suitesparse \
        qt \
        glew \
        sqlite \
        cgal-cpp \
        mesa-libgl-devel-cos7-x86_64 \
        cuda-compiler==12.6.2 \
        cuda-cudart-dev \
        cuda-nvrtc-dev \
        libcurand-dev

    git clone https://github.com/colmap/colmap.git
    cd colmap
    mkdir build
    cd build
    cmake .. -GNinja
    ninja



.. _installation-library:

-------
Library
-------

If you want to include and link COLMAP against your own library, the easiest way
is to use CMake as a build configuration tool. After configuring the COLMAP
build and running ``ninja/make install``, COLMAP automatically installs all
headers to ``${CMAKE_INSTALL_PREFIX}/include/colmap``, all libraries to
``${CMAKE_INSTALL_PREFIX}/lib/colmap``, and the CMake configuration to
``${CMAKE_INSTALL_PREFIX}/share/colmap``.

For example, compiling your own source code against COLMAP is as simple as
using the following ``CMakeLists.txt``::

    cmake_minimum_required(VERSION 3.10)

    project(SampleProject)

    find_package(colmap REQUIRED)
    # or to require a specific version: find_package(colmap 3.4 REQUIRED)

    add_executable(hello_world hello_world.cc)
    target_link_libraries(hello_world colmap::colmap)

with the source code ``hello_world.cc``::

    #include <cstdlib>
    #include <iostream>

    #include <colmap/controllers/option_manager.h>
    #include <colmap/util/string.h>

    int main(int argc, char** argv) {
        colmap::InitializeGlog(argv);

        std::string message;
        colmap::OptionManager options;
        options.AddRequiredOption("message", &message);
        if (!options.Parse(argc, argv)) {
            return EXIT_FAILURE;
        }

        std::cout << colmap::StringPrintf("Hello %s!\n", message.c_str());

        return EXIT_SUCCESS;
    }

Then compile and run your code as::

    mkdir build
    cd build
    export colmap_DIR=${CMAKE_INSTALL_PREFIX}/share/colmap
    cmake .. -GNinja
    ninja
    ./hello_world --message "world"

The sources of this example are stored under ``doc/sample-project``.

----------------
Shared Libraries
----------------

By default, COLMAP builds static libraries. To build shared/dynamic libraries
instead, enable the ``BUILD_SHARED_LIBS`` option::

    cmake .. -GNinja -DBUILD_SHARED_LIBS=ON

Trade-offs compared to static libraries:

- **Faster incremental linking**: Only the changed shared library needs to be
  re-linked during development, rather than all executables.
- **Reduced disk usage**: Multiple executables share the same library files on
  disk and in memory.
- **No cross-library optimization**: The compiler cannot inline or apply
  link-time optimization (LTO/IPO) across shared library boundaries, which
  reduces runtime performance.
- **Symbol resolution overhead**: The dynamic linker resolves symbols at load
  time, adding minor startup cost and indirect call overhead.

For development workflows, shared libraries can significantly speed up
edit-compile-test cycles. For production or benchmarking, static libraries are
recommended.

----------------
AddressSanitizer
----------------

If you want to build COLMAP with address sanitizer flags enabled, you need to
use a recent compiler with ASan support. For example, you can manually install
a recent clang version on your Ubuntu machine and invoke CMake as follows::

    CC=/usr/bin/clang CXX=/usr/bin/clang++ cmake .. \
        -DASAN_ENABLED=ON \
        -DTESTS_ENABLED=ON \
        -DCMAKE_BUILD_TYPE=RelWithDebInfo

Note that it is generally useful to combine ASan with debug symbols to get
meaningful traces for reported issues.

-------------
Documentation
-------------

1. Install latest pycolmap for up-to-date pycolmap API documentation.
2. Build the documentation::

        cd path/to/colmap/doc
        pip install -r requirements.txt
        make html
        open _build/html/index.html # preview results

   Alternatively, you can build the documentation as PDF, EPUB, etc.::

        make latexpdf
        open _build/pdf/COLMAP.pdf

Publishing to the website (`colmap.github.io <https://colmap.github.io/>`__) is
automated: whenever documentation-relevant files change on ``main``, the CI
pipeline builds these docs and pushes the result to the ``master`` branch of the
`colmap/colmap.github.io <https://github.com/colmap/colmap.github.io>`__
repository. Pull requests that touch the docs build them too and upload the
generated HTML as a downloadable ``docs-preview`` artifact for review, without
publishing. The manual steps above are therefore only needed to preview the docs
locally.

For a main release, still copy the previous release as legacy to the "legacy"
folder in the website repository, under a folder with the release number
(`see here <https://github.com/colmap/colmap.github.io/tree/master/legacy>`__).
The automated deploy preserves the existing ``legacy`` folder.
