Getting started

This page covers how to install Trivy, build it from source, run the test suites, and execute a first scan. For the full user-facing documentation see trivy.dev/docs.

Prerequisites

• Go — the version pinned in go.mod (currently go 1.25.8). Older Go versions will not compile Trivy.
• Git — required for repository scans and for tests that exercise the Git artifact handler.
• Mage — optional but recommended for orchestrating builds and code generation. Install with go install github.com/magefile/mage@latest. The Mage tasks are defined under magefiles/.
• Docker (optional) — required for tests that exercise the Docker engine artifact handler in integration/docker_engine_test.go.
• Container runtime (optional) — containerd, podman, or docker for image scanning against a local daemon.

Install (binary)

Trivy ships pre-built binaries for every release:

• brew install trivy (macOS / Linux)
• docker run --rm aquasec/trivy:latest <command>
• Direct download from GitHub releases

Distribution-specific installers are listed in the installation docs.

Build from source

The simplest way to build:

go build -o trivy ./cmd/trivy
./trivy --version

The Mage workflow (magefiles/magefile.go) wraps this and several other tasks:

# List all mage targets
mage -l

# Build the binary
mage build

# Run unit tests
mage test:unit

# Run integration tests (slow; requires Docker)
mage test:integration

Trivy is released through goreleaser (goreleaser.yml) and release-please (release-please-config.json, .github/workflows/release-please.yaml). Local users do not run these directly.

First scan

# Scan a public container image
./trivy image python:3.4-alpine

# Scan a local filesystem
./trivy fs --scanners vuln,secret,misconfig myproject/

# Scan a Git repository
./trivy repo https://github.com/aquasecurity/trivy

# Generate a CycloneDX SBOM
./trivy image --format cyclonedx --output sbom.json my/image:tag

# Scan an existing SBOM
./trivy sbom sbom.json

# Run as a server
./trivy server --listen :8080
./trivy image --server http://localhost:8080 alpine:3.18

The first run downloads the Trivy DB (80 MB compressed) into `/.cache/trivy/. Subsequent runs reuse the cache; pass --skip-db-updateto skip the version check or--cache-dir` to relocate it.

Configuration

Trivy reads flags, environment variables, and a YAML config file. Precedence is flag > environment > config.

• Default config file: trivy.yaml in the current directory (or --config-file).
• Environment variables follow the TRIVY_* convention (TRIVY_SEVERITY=HIGH,CRITICAL).
• See pkg/flag/options.go for the full surface area and pkg/flag/global_flags.go for global flags.

Examples of common flags:

trivy image --severity HIGH,CRITICAL --ignore-unfixed alpine:latest
trivy fs --scanners vuln,misconfig,secret --format sarif -o trivy.sarif .
trivy k8s --report summary cluster

Running tests

Unit tests live next to the code (*_test.go). Run all of them:

go test ./...

The codebase has ~1,700 Go files and 626 test files. Long-running tests are skipped in -short mode.

Integration tests live in integration/ and require Docker, network access, and a local registry container. They are gated by build tags:

go test -tags=integration ./integration/...

The CI matrix in .github/workflows/test.yaml runs unit tests, integration tests, and module tests in separate jobs.

Documentation site

The user-facing documentation lives under docs/ and is built with MkDocs (config in mkdocs.yml). To preview locally:

pip install -r docs/requirements.txt   # if a requirements file is added
mkdocs serve

The docs site is published from the mkdocs-latest.yaml workflow on each merge to main.

Where to go next

• Apps → CLI — command tree details.
• How to contribute — branching, PRs, and review.
• Patterns and conventions — error handling, logging, error wrapping with xerrors.
• Reference → Configuration — every config option.