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 mergekeeps 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-covdbginstalls the build for the runner's architecture, so an ARM64 runner gets the ARM64 build.
Installation Methods
Installer (Recommended)
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.
- Download the installer from covdbg.com/download/latest/installer.msi, or for Windows on ARM covdbg.com/download/latest/installer-arm64.msi
- Run the installer. There is no elevation prompt; you can choose a different directory in the wizard
- Follow the installation wizard
- 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.
- Download the ZIP archive from covdbg.com/download/latest/portable.zip, or for Windows on ARM covdbg.com/download/latest/portable-arm64.zip
- Extract to a directory of your choice (e.g.,
C:\Tools\covdbg) - 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")
- 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
- Remove the installation directory
- Remove covdbg from your PATH
Next Steps
- Follow the Quick Start Guide
- Read the CLI Reference
- Configure your project with .covdbg.yaml