How to Install GoogleTest for C++ Projects: CMake and Bazel Setup Guide

Install GoogleTest for C++ projects by integrating it as a source dependency via CMake FetchContent or the Bazel Central Registry, both of which automatically build the gtest and gtest_main libraries and make their headers available to your test binaries.

GoogleTest (gtest) is a widely-used C++ unit testing framework maintained by Google that ships as source code designed to be compiled alongside your project. Because the framework consists of header files in googletest/include/gtest/ and compiled libraries built from googletest/src/, installation simply requires making these components available to your build system. This guide covers the two canonical integration methods based on the official google/googletest repository structure.

CMake FetchContent Method

The CMake FetchContent approach is the recommended way to install GoogleTest for projects already using CMake. This method downloads the source archive from GitHub, builds the gtest and gtest_main targets, and makes them available as GTest::gtest and GTest::gtest_main without requiring external package managers.

Declare the Dependency

Create or modify your root CMakeLists.txt to include the FetchContent module and declare GoogleTest as a dependency. According to docs/quickstart-cmake.md【/cache/repos/github.com/google/googletest/main/docs/quickstart-cmake.md†L49-L67】, you must set the C++ standard to at least 17 and use the FetchContent_Declare command to pull the specific release archive:

cmake_minimum_required(VERSION 3.14)
project(my_project)

# GoogleTest requires at least C++17

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

include(FetchContent)
FetchContent_Declare(
  googletest
  URL https://github.com/google/googletest/archive/03597a01ee50ed33e9dfd640b249b4be3799d395.zip
)

# Prevent overriding parent project's CRT settings on Windows

set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
FetchContent_MakeAvailable(googletest)

Link to Your Test Executable

After making the content available, enable testing and link your test binary to GTest::gtest_main, which provides the main() function:

enable_testing()

add_executable(
  hello_test
  hello_test.cc
)
target_link_libraries(
  hello_test
  GTest::gtest_main
)

include(GoogleTest)
gtest_discover_tests(hello_test)

The GTest::gtest_main target combines the core library with a default test runner, eliminating the need to write your own main() function.

Bazel Central Registry Method

For projects using Bazel, install GoogleTest by declaring it as a module dependency in the Bazel Central Registry. This method automatically fetches pre-packaged targets @googletest//:gtest and @googletest//:gtest_main as documented in docs/quickstart-bazel.md【/cache/repos/github.com/google/googletest/main/docs/quickstart-bazel.md†L45-L52】.

Configure MODULE.bazel

Create a MODULE.bazel file in your project root to declare the dependency:

# Choose the most recent version at

# https://registry.bazel.build/modules/googletest

bazel_dep(name = "googletest", version = "1.18.0")

Define BUILD Targets

Create a BUILD file that defines a cc_test rule linking against the GoogleTest targets as shown in docs/quickstart-bazel.md【/cache/repos/github.com/google/googletest/main/docs/quickstart-bazel.md†L84-L92】:

cc_test(
    name = "hello_test",
    size = "small",
    srcs = ["hello_test.cc"],
    deps = [
        "@googletest//:gtest",
        "@googletest//:gtest_main",
    ],
)

Bazel automatically handles downloading, building, and linking the GoogleTest libraries when you run bazel test //:hello_test.

Manual Installation (Advanced)

If you require full control over the installation location or need to install GoogleTest system-wide, clone the repository and build it manually using CMake or Bazel from within the googletest directory. This generates static libraries from googletest/src/gtest-all.cc and headers from googletest/include/gtest/ that you can install to system paths. However, this approach is rarely necessary because the FetchContent and Bazel methods handle building and linking automatically while respecting the minimum C++17 requirement introduced in version 1.18.x【/cache/repos/github.com/google/googletest/main/README.md†L13-L18】.

Key Source Files and Architecture

Understanding the repository structure helps clarify how installation works:

• googletest/include/gtest/*.h – Header-only API providing testing macros and assertion functions used by test code.
• googletest/src/gtest-all.cc – Source file that compiles into the core gtest library containing the testing framework implementation.
• BUILD.bazel – Defines the Bazel build rules for the library itself, exposing the :gtest and :gtest_main targets.
• docs/quickstart-cmake.md and docs/quickstart-bazel.md – Official quick-start guides containing authoritative integration instructions.

Summary

• CMake projects should use FetchContent_Declare to download GoogleTest source and link against GTest::gtest_main for automatic test discovery via gtest_discover_tests.
• Bazel projects should declare googletest as a bazel_dep in MODULE.bazel and depend on @googletest//:gtest_main in cc_test rules.
• C++17 is required for GoogleTest versions 1.18.x and later, enforced via CMAKE_CXX_STANDARD or Bazel toolchain configuration.
• Both methods build from source located in googletest/src/ and expose headers from googletest/include/gtest/, eliminating the need for separate library installation.

Frequently Asked Questions

What is the minimum C++ standard required to install GoogleTest?

GoogleTest requires C++17 or later as of version 1.18.x. You must set CMAKE_CXX_STANDARD 17 in CMake projects or configure equivalent compiler flags in Bazel. Older projects using C++11 or C++14 must upgrade their toolchain or use an older GoogleTest release.

Should I link to gtest or gtest_main when installing GoogleTest?

Link to gtest_main if you want GoogleTest to provide the main() function automatically. Link to gtest only if you are writing your own main() function with custom initialization logic. Both targets are available through CMake FetchContent (GTest::gtest_main) and Bazel (@googletest//:gtest_main).

Can I install GoogleTest using system package managers like apt or vcpkg?

While package managers offer GoogleTest binaries, the FetchContent and Bazel methods are preferred because they ensure version consistency across development environments and automatically build the library with your project's exact compiler settings and flags. The google/googletest repository is specifically designed for source integration.

Why does Windows require gtest_force_shared_crt when installing with CMake?

Setting gtest_force_shared_crt ON prevents GoogleTest from overriding the C Runtime Library (CRT) settings on Windows, ensuring compatibility with the parent project's runtime configuration. Without this flag, you may encounter linker errors when mixing static and dynamic CRT libraries in Visual Studio builds.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}