Skip to main content
This guide covers building the Internet Computer Protocol from source using the Bazel build system.

​
Prerequisites

Before building, ensure you have:
  • Met all system requirements
  • Cloned the IC repository
  • A clean Git working directory (no uncommitted changes)
The build script will fail if your Git working directory is not clean. Commit or stash your changes before building.

​
Quick Start

The simplest way to build the IC is using the containerized build script: 
# Build all IC-OS images
./ci/container/build-ic.sh -i

# Build binaries and canisters
./ci/container/build-ic.sh -b -c
Built artifacts are located in the artifacts/ directory at the repository root.

​
Build Script Options

The build-ic.sh script provides several options for building different components:

​
Command-Line Flags

​
-b, --binaries
flag
Build IC binaries
​
-c, --canisters
flag
Build IC canisters
​
-i, --icos
flag
Build IC-OS images (GuestOS, HostOS, SetupOS, Recovery)
​
-n, --no-release
flag
Non-release build (for non-protected branches not in rc—* or master)
​
-h, --help
flag
Display help information

​
Usage Examples

./ci/container/build-ic.sh -b

​
Build Targets

The build script uses Bazel targets to build different components:

​
Binaries

bazel build //publish/binaries:bundle
Output location: artifacts/release/

​
Canisters

bazel build //publish/canisters:bundle
Output location: artifacts/canisters/

​
IC-OS Images

bazel build \
  //ic-os/guestos/envs/prod:bundle-update \
  //ic-os/hostos/envs/prod:bundle-update \
  //ic-os/setupos/envs/prod:bundle \
  //ic-os/guestos/envs/recovery:bundle-update
Output location: artifacts/icos/

​
Bazel Build Process

​
Build Configuration

The build script uses common Bazel arguments: 
bazel build \
  --config=local \
  --color=yes \
  [--config=stamped]  # For release builds
Release builds (on master or rc--* branches) use the --config=stamped flag:
bazel build --config=local --config=stamped <targets>
This includes version information in the built artifacts.

​
Build Artifacts

After building, artifacts are organized by type: 
artifacts/
├── release/          # Binaries
│   ├── canister_sandbox
│   ├── ic-admin
│   ├── orchestrator
│   ├── replica
│   └── SHA256SUMS
├── canisters/        # Canisters
│   ├── governance-canister.wasm
│   ├── ledger-canister.wasm
│   └── SHA256SUMS
└── icos/            # IC-OS images
    ├── guestos/
    │   ├── update/
    │   │   ├── update-img.tar.zst
    │   │   └── SHA256SUMS
    │   └── update-img-recovery/
    ├── hostos/
    │   └── update/
    ├── setupos/
Each directory includes a SHA256SUMS file with checksums for verification.

​
Building Specific Components

​
Building Individual IC-OS Images

You can build specific IC-OS images directly with Bazel: 
# Production GuestOS
bazel build //ic-os/guestos/envs/prod/...

# Development GuestOS (with console access)
bazel build //ic-os/guestos/envs/dev/...

# Recovery GuestOS
bazel build //ic-os/guestos/envs/recovery/...
Output: bazel-bin/ic-os/guestos/envs/<env>/
# Production HostOS
bazel build //ic-os/hostos/envs/prod/...

# Development HostOS
bazel build //ic-os/hostos/envs/dev/...
Output: bazel-bin/ic-os/hostos/envs/<env>/
# Production SetupOS
bazel build //ic-os/setupos/envs/prod/...

# Development SetupOS
bazel build //ic-os/setupos/envs/dev/...
Output: bazel-bin/ic-os/setupos/envs/<env>/
Development images (dev targets) allow console access with username/password: root/rootProduction images (prod targets) have console access disabled for security.

​
Containerized Build

The containerized build automatically handles the environment setup: 
./ci/container/build-ic.sh -i
This script:
  1. Checks if running inside the ic-build container
  2. If not, drops into the container using container-run.sh
  3. Runs the build inside the container
  4. Copies artifacts to the host’s artifacts/ directory
The container is defined in ci/container/Dockerfile and includes all necessary dependencies.

​
Manual Build (Without Container)

If you have all dependencies installed locally: 
# Set up environment
export VERSION="$(git rev-parse HEAD)"

# Build binaries
bazel build --config=local --config=stamped //publish/binaries:bundle

# Build canisters  
bazel build --config=local --config=stamped //publish/canisters:bundle

# Build IC-OS images
bazel build --config=local --config=stamped \
  //ic-os/guestos/envs/prod:bundle-update \
  //ic-os/hostos/envs/prod:bundle-update \
  //ic-os/setupos/envs/prod:bundle \
  //ic-os/guestos/envs/recovery:bundle-update

​
Troubleshooting

The build requires a clean Git state.
# Check status
git status

# Commit or stash changes
git stash
# or
git commit -am "WIP"
This indicates the container detection failed. Try cleaning up and rebuilding:
unset BUILD_IC_NESTED
./ci/container/build-ic.sh -i
Bazel builds can consume significant disk space. Ensure you have at least 100 GB free.
# Clean Bazel cache
bazel clean --expunge

# Check disk space
df -h .
Install Podman for containerized builds:
sudo apt-get update
sudo apt-get install -y podman
Ensure you’re using the correct Bazel version:
# Check required version
cat .bazelversion

# Install specific version
# Follow instructions at https://bazel.build/install

​
Build Performance Tips

Use Local Cache

Bazel caches build outputs. Subsequent builds are much faster.

Parallel Builds

Bazel automatically parallelizes builds based on available CPU cores.

Build Specific Targets

Only build what you need to save time and disk space.

More RAM

More RAM improves build performance, especially for linking.

​
Verifying Build Outputs

After building, verify the checksums: 
# Verify binaries
cd artifacts/release
sha256sum -c SHA256SUMS

# Verify canisters
cd artifacts/canisters  
sha256sum -c SHA256SUMS

# Verify IC-OS images
cd artifacts/icos/guestos/update
sha256sum -c SHA256SUMS

​
Next Steps

Verifying Releases

Learn how to verify build reproducibility

IC-OS Overview

Deep dive into IC-OS architecture

Build docs developers (and LLMs) love

Get started for freeTalk to us