/commands/cmake/install-prefix
cmake --install build --prefix: install a CMake project to a custom directory
- tool
- CMake
- versions
- CMake 3.15+ (cmake --install), CMake 4.x
- os
- linux, macos, windows
To install a CMake project somewhere other than the default, build it and run cmake --install build --prefix /path/to/dir. --install (CMake 3.15 and later) runs the install() rules of an already-configured build directory, and --prefix overrides CMAKE_INSTALL_PREFIX for this run only, without reconfiguring. The default prefix is /usr/local on Linux and macOS and a folder under Program Files on Windows.
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
cmake --install build --prefix "$HOME/.local"Install into a folder you own
The project installs one generated file with install(FILES ...), so it needs no compiler. CMake comes from PyPI through uv here:
cat > CMakeLists.txt <<'EOF'
cmake_minimum_required(VERSION 3.20)
project(demo NONE)
file(WRITE ${CMAKE_BINARY_DIR}/demo.conf "level=1\n")
install(FILES ${CMAKE_BINARY_DIR}/demo.conf DESTINATION etc/demo)
install(FILES ${CMAKE_BINARY_DIR}/demo.conf DESTINATION share/doc/demo COMPONENT docs)
EOF
cmake() { uv run -q --no-project --python 3.13 --with cmake==4.4.4 --with ninja==1.13.0 cmake "$@"; }
cmake -S . -B build -G Ninja > /dev/null && cmake --build build
cmake --install build --prefix out > /dev/null
find out -type f | sort
echo '--- docs component only'
cmake --install build --prefix docs-only --component docs > /dev/null
find docs-only -type fOutput
ninja: no work to do. out/etc/demo/demo.conf out/share/doc/demo/demo.conf --- docs component only docs-only/share/doc/demo/demo.conf
DESTINATION paths are relative to the prefix, which is what makes --prefix work. A rule with an absolute DESTINATION ignores the prefix.
Options
| Option | Effect |
|---|---|
| --prefix DIR | install under DIR instead of CMAKE_INSTALL_PREFIX |
| --config CFG | which configuration to install with multi-config generators (Visual Studio, Xcode, Ninja Multi-Config) |
| --component NAME | install only the rules tagged COMPONENT NAME; CMake 4.4+ accepts several names |
| --strip | strip binaries before installing them |
| -v, --verbose | verbose output (also enabled by the VERBOSE environment variable) |
| -j N, --parallel N | install in parallel (CMake 3.31+, only when the INSTALL_PARALLEL property is on) |
| DESTDIR=/stage (environment) | prepend a staging root on Unix-style installs, for packaging |
Two older forms still work: -DCMAKE_INSTALL_PREFIX=DIR at configure time sets the prefix permanently in the cache, and cmake --build build --target install builds and installs in one step with the cached prefix.
Stage for a package with DESTDIR
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/usr
cmake --build build
DESTDIR="$PWD/pkgroot" cmake --install buildThe files go to pkgroot/usr/... while the project still believes it is installed in /usr, which is what .deb, .rpm and Homebrew build scripts expect. DESTDIR is meant for Unix layouts; on Windows the drive letter is dropped, which makes it less useful there.
Pitfalls
- Permission denied under /usr/local. Installing to the default prefix needs root on Linux and macOS. Prefer
--prefix "$HOME/.local"over running the whole build withsudo. - Multi-config generators. With Visual Studio or Xcode,
cmake --install buildinstalls the Release configuration by default when you omit--config; pass--config Debugto install the Debug build. - Consumers cannot find the package. After installing a library to a custom prefix, other projects need
-DCMAKE_PREFIX_PATH=DIR, otherwise they fail with Could not find a package configuration file. - Nothing to install. A project without
install()rules installs nothing and prints no error: the output lists noInstalling:lines. - GNUInstallDirs. Some paths from the GNUInstallDirs module are computed from the prefix at configure time and keep that value even when
--prefixchanges at install time; setCMAKE_INSTALL_PREFIXat configure time when that matters.
FAQ
What is the default CMAKE_INSTALL_PREFIX?
/usr/local on Linux and macOS, and a folder named after the project under Program Files on Windows. Installing there usually needs root or administrator rights, which is why --prefix to a folder you own is common.
What is the difference between --prefix and DESTDIR?
--prefix (or CMAKE_INSTALL_PREFIX) is where the files are meant to live and can be recorded in the installed files. DESTDIR is a staging root put in front of that path for packaging, so the files land in DESTDIR/usr/local/... while still describing themselves as /usr/local.
Why does cmake --install say the build directory has no cmake_install.cmake?
The directory was never configured, or it is the source directory. Run cmake -S . -B build first and pass the build directory, not the source directory, to --install.