Upgrade CMake on Ubuntu/Debian: Install a Newer Release and Fix Common Build Errors
Tech
2
When a project fails with "CMake 3.8 or higher is required" (or similar), your system’s CMake is too old. Below are two ways to install a newer CMake and how to resolve common issues during the process.
1. Check the current CMake version
cmake --version
2. Remove the distribution CMake (optional)
If another package (e.g., ROS) depends on the distro CMake, skip removal.
sudo apt remove cmake
# or, to fully purge the package and unused dependencies:
# sudo apt purge --autoremove cmake cmake-data
3. Install a newer CMake
You can use either the prebuilt binary tarball (no compilation) or build from source.
Option A: Use the official prebuilt binary
- Download the latest binary tarball from https://cmake.org/download/ (Linux x86_64) or via
wget:
CMAKE_VER=3.28.6
CMAKE_MM=3.28
wget "https://cmake.org/files/v${CMAKE_MM}/cmake-${CMAKE_VER}-linux-x86_64.tar.gz"
- Extract and place it somewhere permanent (e.g., /opt):
sudo mkdir -p /opt/cmake
sudo tar -xzf cmake-${CMAKE_VER}-linux-x86_64.tar.gz -C /opt/cmake --strip-components=1
- Make the new CMake available on PATH:
# Add to PATH for the current shell session
export PATH=/opt/cmake/bin:$PATH
# Or create a system-wide symlink
sudo ln -sfn /opt/cmake/bin/cmake /usr/local/bin/cmake
sudo ln -sfn /opt/cmake/bin/ctest /usr/local/bin/ctest
sudo ln -sfn /opt/cmake/bin/cpack /usr/local/bin/cpack
Option B: Build from source
- Install build tools and headers:
sudo apt update
sudo apt install -y build-essential libssl-dev
- Download the source tarball and unpack:
CMAKE_VER=3.28.6
CMAKE_MM=3.28
wget "https://cmake.org/files/v${CMAKE_MM}/cmake-${CMAKE_VER}.tar.gz"
tar -xzf cmake-${CMAKE_VER}.tar.gz
cd cmake-${CMAKE_VER}
- Configure, build, and install:
# Enable OpenSSL support; remove the flag or set -DCMAKE_USE_OPENSSL=OFF if you don’t need it
./bootstrap -- -DCMAKE_USE_OPENSSL=ON
make -j"$(nproc)"
sudo make install
- Verify:
cmake --version
Notes on choosing binaries vs source
- "Source" archives (tar.gz) require compilation (Option B).
- "Binary distributions" for Linux x86_64 are precompiled and can be used immediately (Option A) by adjusting PATH or creating symlinks.
Troubleshooting
1) Bootstrap fails: OpenSSL not found
Symptoms during ./bootstrap:
Could NOT find OpenSSL ...
CMake Error at Utilities/cmcurl/CMakeLists.txt:... (message):
Could not find OpenSSL. Install an OpenSSL development package or configure CMake with -DCMAKE_USE_OPENSSL=OFF
Fix:
sudo apt install -y libssl-dev
# then rerun
./bootstrap -- -DCMAKE_USE_OPENSSL=ON
Alternative, build with out OpenSSL:
./bootstrap -- -DCMAKE_USE_OPENSSL=OFF
2) Installation fails due to permissions
Error during make install:
file cannot create directory: /usr/local/doc/cmake-<ver>. Maybe need administrative privileges.
make: *** [install] Error 1
Fix with elevated privileges:
sudo make install
Or install to a user prefix and adjust PATH:
# from the source tree
dist_dir="$HOME/.local"
./bootstrap --prefix="$dist_dir" -- -DCMAKE_USE_OPENSSL=ON
make -j"$(nproc)"
make install
export PATH="$dist_dir/bin:$PATH"
3) cmake --version fails with "No such file or directory"
Symptom:
bash: /usr/bin/cmake: No such file or directory
Causes include a stale symlink or PATH not including the new location.
- Find the installed binary:
which cmake
# or
command -v cmake
- If CMake is under /usr/local/bin but the system looks in /usr/bin, create or update a symlink:
sudo ln -sfn /usr/local/bin/cmake /usr/bin/cmake
- If you installed to a custom prefix (e.g., /opt/cmake or $HOME/.local), ensure PATH includes its bin directory:
export PATH=/opt/cmake/bin:$PATH
# or
export PATH="$HOME/.local/bin:$PATH"
- If the shell caches command paths, clear it:
hash -r
