Fetch and verify your dependencies once in a controlled step, store them in a mirror or source directory, and point FetchContent at them with FETCHCONTENT_SOURCE_DIR. Turning on FETCHCONTENT_FULLY_DISCONNECTED then stops downloads. It does not prevent network access on the very first run.
Why build offline
Release machines for devices are often isolated. An offline build also means a deleted upstream repository or a network outage cannot stop a release, and a changed remote cannot slip new code into it.
The CMake options
The FetchContent documentation describes these.
- FETCHCONTENT_FULLY_DISCONNECTED is off by default. When on, no attempt is made to download or update any content. It assumes the content was populated by an earlier run or supplied manually. The docs warn it is not an appropriate way to prevent any network access on the first run. From CMake 3.30 the already-populated requirement is enforced under policy CMP0170.
- FETCHCONTENT_SOURCE_DIR_name points a dependency at a local source folder instead of downloading it.
- FETCHCONTENT_UPDATES_DISCONNECTED only stops the update step from contacting remotes for git and Mercurial. Downloads still happen, and switching to an unknown commit hash will fail.
A reliable pattern
- In a connected, controlled job, fetch each dependency at a pinned commit hash or with URL_HASH.
- Verify and archive the sources in an internal mirror.
- Record each source and hash in your SBOM.
- In the release build, set the source directory option for each dependency and turn on the disconnected option.
- Run the release build on a machine with no outbound network to prove it works.
| Control | What it gives you |
|---|---|
| Pinned hash | Same content every time |
| Internal mirror | Survives upstream removal |
| Disconnected option | Stops silent downloads |
| Network-isolated test build | Proof the build is self-contained |
Do not trust the flag alone
Because the documentation says the flag is not a way to block all network access on a first run, test the isolation at the network level. If the build succeeds with no network, you know it does not depend on one.
Keep it fresh
An offline mirror is a snapshot. Schedule a regular job that checks for new releases and advisories for what you mirror, so isolation does not turn into neglect.
Where Safeguard fits
Safeguard provides SBOM and dependency scanning, reachability analysis, and policy gates for the source repositories and manifests it supports, and you can run a free scan at gold.safeguard.sh/scan. Check coverage for your build system before relying on it.
Quick check
Does the disconnected flag replace hash pinning?
No. Pinning decides what content you get. The flag decides whether CMake tries to fetch it.
What if the content is missing in disconnected mode?
The build is expected to fail, since it assumes the content was populated earlier.
Sources
Last reviewed: 19 October 2026.
