# Installation Guide

- Section: Documentation > Getting Started > Installation Guide
- Canonical: https://covdbg.com/docs/getting-started/installation/

---

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

## System Requirements

| Requirement | Minimum |
|-------------|---------|
| Operating System | Windows 10 or Windows 11 |
| Architecture | x64 |
| Debug Symbols | PDB files required for coverage |

## 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.

1. Download the installer from [covdbg.com/download/latest/installer.msi](/download/latest/installer.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:

```powershell
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](/download/latest/portable.zip)
2. Extract to a directory of your choice (e.g., `C:\Tools\covdbg`)
3. Add the directory to your PATH manually:

```powershell
# 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")
```

4. Open a new terminal and verify:

```powershell
covdbg --help
```

## Components

The installation includes:

| Component | Description |
|-----------|-------------|
| `covdbg.exe` | Command-line coverage tool |
| `libcovdbg.dll` | Coverage agent, loaded into the program under test |

## 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 sign-in or a project 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.

**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:

```powershell
covdbg login
```

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

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

Visit our [Pricing page](https://app.covdbg.com/pricing) for seats, or the [Open Source Program](/company/programs/open-source-program/) if your code is public. See the [CLI Reference](/docs/reference/cli-reference/) for how a run's credential is resolved, and the [Licensing FAQ](/docs/reference/licensing-faq/) for the personal lock, seats and CI.

## Verifying Installation

Run a quick test to verify everything works:

```powershell
# 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

* Follow the [Quick Start Guide](/docs/getting-started/quick-start/)
* Read the [CLI Reference](/docs/reference/cli-reference/)
* Configure your project with [.covdbg.yaml](/docs/reference/configuration/)