Installation Guide

covdbg provides code coverage for native Windows applications. This guide covers installation and system requirements.

System Requirements

Requirement Minimum
Operating System Windows 10, Windows 11, or Windows Server 2016 or later
Architecture x64 or ARM64 (Windows on ARM); the x64 build also measures 32-bit x86 programs
Debug Symbols PDB files required for coverage

There is one covdbg build per architecture. The x64 build measures x64 binaries and, from covdbg 1.5.0, 32-bit x86 programs, which Windows runs under WOW64: its installer and ZIP include libcovdbg32.dll, a 32-bit build of the agent, so there is no separate 32-bit covdbg. The ARM64 build measures ARM64 binaries.

Windows on ARM

From covdbg 1.5.0, covdbg runs natively on Windows on ARM. Install the ARM64 build there to measure the ARM64 programs you build:

covdbg build Measures Downloads
x64 x64 and 32-bit x86 programs installer, portable ZIP
ARM64 ARM64 programs installer, portable ZIP
  • A program the build does not measure is refused before it starts: covdbg exits with code 1 and names the build to use. See A program of another architecture is refused.
  • With --follow-children, a child process of another architecture, such as an x64 tool that an ARM64 test starts, runs un-instrumented and the run goes on. The log names it.
  • ARM64EC images are measured by neither build.
  • covdbg merge keeps the x64 and ARM64 builds of one program side by side, and the lines of the sources they share add up, so the coverage of both builds makes one report.
  • The VS Code extension bundles the ARM64 covdbg on Windows on ARM. In GitHub Actions, liasoft/setup-covdbg installs the build for the runner's architecture, so an ARM64 runner gets the ARM64 build.

Installation Methods

The installer performs a per-user installation to %LocalAppData%\Programs\Liasoft\covdbg and adds that directory to your user PATH. Nothing is written outside your profile, so no Administrator rights are needed. This is the recommended method for most users.

  1. Download the installer from covdbg.com/download/latest/installer.msi, or for Windows on ARM covdbg.com/download/latest/installer-arm64.msi
  2. Run the installer. There is no elevation prompt; you can choose a different directory in the wizard
  3. Follow the installation wizard
  4. Open a new terminal and verify:
covdbg --help

Note: Existing terminal sessions need to be restarted to pick up the updated PATH. Because the installation is per user, covdbg is on the PATH for your account only. Another account on the same machine, or a service or build agent running as a different user, needs its own installation.

Portable Installation

The ZIP archive provides a portable installation that can be placed anywhere and does not modify system settings. This is useful for restricted environments or when you want to run multiple versions side-by-side.

  1. Download the ZIP archive from covdbg.com/download/latest/portable.zip, or for Windows on ARM covdbg.com/download/latest/portable-arm64.zip
  2. Extract to a directory of your choice (e.g., C:\Tools\covdbg)
  3. Add the directory to your PATH manually:
# Temporary: Add to PATH for current session only
$env:PATH += ";C:\Tools\covdbg"

# Permanent: Add to user PATH (no admin required)
[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";C:\Tools\covdbg", "User")
  1. Open a new terminal and verify:
covdbg --help

Components

The installation includes:

Component Description
covdbg.exe Command-line coverage tool
libcovdbg.dll Coverage agent, loaded into the program under test
libcovdbg32.dll Coverage agent for 32-bit programs (x64 package), from covdbg 1.5.0

Keep these files together in one folder. covdbg.exe looks for its agent only beside itself, so copy or move the whole folder, never covdbg.exe alone. From covdbg 1.5.0, a run whose agent DLL is missing stops before the program under test starts and exits with code 1; see Agent DLL not found.

The .covdbg Directory

covdbg keeps what a run writes in .covdbg, in the working directory it is started from. Nothing goes to an application data folder under your profile, so every project keeps its own directory next to its .covdbg.yaml. It is created on the first run.

Path Description
coverage.covdb The coverage database of a run, unless --output names another path
Logs/covdbg.log Rotating log files, DEBUG level and above, unless --log-file names another path

Add .covdbg/ to your .gitignore. Your sign-in (covdbg login) is kept in the Windows Credential Manager, not on disk.

Signing In

Runs are licensed per seat: the license service decides every run from the repository and the commit author, and every run carries a credential: a sign-in, a project token, or, on GitHub Actions, the job's own workflow token. Public repositories are free for whoever asks; a sign-in covers one private repository at a time until a team seats you, and CI carries the team's token, except a public repository on GitHub Actions, which needs no secret.

Local development: Sign in once. covdbg login shows a code and a page to open; confirm the code there with your GitHub account, and the sign-in is kept in the Windows Credential Manager. The sign-in ends with choosing the team to sign in for, or you name it up front with covdbg login --team <slug> (see the sign-in commands):

covdbg login

CI/CD: Set a project token (store it as a secret):

$env:COVDBG_PROJECT_TOKEN = "<your-project-token>"

On GitHub Actions a public repository needs no token: grant the job id-token: write, see GitHub Actions.

Visit our Pricing page for seats, or the Open Source Program if your code is public. See the CLI Reference for how a run's credential is resolved, and the Licensing FAQ for the personal lock, seats and CI.

Verifying Installation

Run a quick test to verify everything works:

# Check version and help
covdbg --help

# Test with a simple program (if you have one built with PDBs)
covdbg --output "test.covdb" "your_program.exe"

Updating covdbg

Installation: Download and run the latest installer. It will automatically upgrade the existing installation.

Portable Installation: Extract the new version over the existing directory, replacing all files.

Uninstalling

Installation

Use Windows "Add or Remove Programs" to uninstall covdbg. The entry is listed under your own account, and removing it does not need Administrator rights.

Manual Installation

  1. Remove the installation directory
  2. Remove covdbg from your PATH

Next Steps