# How to Configure Trivy with a Config File Instead of Command-Line Flags

> Learn how to configure Trivy with a YAML config file instead of command line flags. Streamline your security scanning with this maintainable approach.

- Repository: [Aqua Security/trivy](https://github.com/aquasecurity/trivy)
- Tags: how-to-guide
- Published: 2026-03-23

---

**You can configure Trivy using a YAML configuration file (default [`trivy.yaml`](https://github.com/aquasecurity/trivy/blob/main/trivy.yaml)) by using the `--config` flag, which leverages the Viper library to load settings before any subcommands execute, allowing you to replace repetitive CLI flags with a single maintainable file.**

The **aquasecurity/trivy** repository supports declarative configuration through YAML files, eliminating the need to pass long flag strings for every scan. This approach centralizes your scanning policies and makes CI/CD pipelines easier to maintain.

## How Trivy Loads Configuration Files

Trivy’s configuration system is built on top of the **Viper** library, which handles file discovery, parsing, and merging with default values.

### The Initialization Flow

When the CLI starts, Trivy executes a specific sequence to load your configuration:

1. **Flag Registration** – The `--config` (or `-c`) flag is defined in [`pkg/flag/global_flags.go`](https://github.com/aquasecurity/trivy/blob/main/pkg/flag/global_flags.go) as `ConfigFileFlag` [[source]](https://github.com/aquasecurity/trivy/blob/main/pkg/flag/global_flags.go#L16). This flag accepts the path to your configuration file.

2. **Viper Initialization** – In [`pkg/commands/app.go`](https://github.com/aquasecurity/trivy/blob/main/pkg/commands/app.go), the `initConfig` function initializes Viper and calls `viper.SetConfigFile(configFile)` to specify which file to read [[source]](https://github.com/aquasecurity/trivy/blob/main/pkg/commands/app.go#L149-L162).

3. **Value Merging** – Viper loads the file and merges its values with built-in defaults. All command-line flags are subsequently bound to the same Viper instance, ensuring that flags override file values when conflicts occur.

If the file cannot be opened or parsed, `initConfig` returns an error such as “config file *X* loading error: …” [[source]](https://github.com/aquasecurity/trivy/blob/main/pkg/commands/app.go#L160-L162).

## Creating and Using a Trivy Config File

### Default File Location and Discovery

By default, Trivy looks for a file named **[`trivy.yaml`](https://github.com/aquasecurity/trivy/blob/main/trivy.yaml)** in the current working directory. If present, Trivy automatically loads it without requiring the `--config` flag. The file must contain valid YAML that conforms to the JSON schema stored in [`schema/trivy-config.json`](https://github.com/aquasecurity/trivy/blob/main/schema/trivy-config.json) [[source]](https://github.com/aquasecurity/trivy/blob/main/schema/trivy-config.json).

### Generating a Starter Config File

Trivy includes a built-in helper to generate a default configuration file. The implementation resides in [`pkg/commands/artifact/run.go`](https://github.com/aquasecurity/trivy/blob/main/pkg/commands/artifact/run.go), which handles the `--generate-default-config` flag [[source]](https://github.com/aquasecurity/trivy/blob/main/pkg/commands/artifact/run.go#L384-L393).

Run the following command to create [`trivy-default.yaml`](https://github.com/aquasecurity/trivy/blob/main/trivy-default.yaml) in your current directory:

```bash
trivy config init

```

Rename the file if you prefer the standard name:

```bash
mv trivy-default.yaml trivy.yaml

```

### Custom Config File Paths

To use a config file located elsewhere, specify the path with the `--config` flag:

```bash
trivy --config /etc/trivy/custom.yaml fs /my/project

```

You can also use the short form:

```bash
trivy -c /etc/trivy/custom.yaml image nginx:latest

```

## Trivy Configuration File Structure

The configuration file supports all global options and subcommand-specific settings. Here is a minimal example that configures severity levels, enables specific scanners, and sets registry credentials:

```yaml

# trivy.yaml

# Global options

severity: "HIGH,CRITICAL"
ignore-unfixed: true

# Scanners you want to enable (comma-separated or list)

scanners:
  - vuln
  - secret
  - config

# Registry credentials (optional)

registry:
  username: myuser
  password: mypass

```

After creating this file in your working directory, run Trivy normally:

```bash
trivy image nginx:latest

```

## Overriding Config File Values with CLI Flags

Command-line flags take precedence over configuration file values. This allows you to maintain baseline settings in [`trivy.yaml`](https://github.com/aquasecurity/trivy/blob/main/trivy.yaml) while overriding specific options for individual runs.

For example, to use your config file but change the severity threshold for a single scan:

```bash
trivy --config ./trivy.yaml --severity MEDIUM,LOW image alpine:3.12

```

Viper processes the file first, then applies the flag value, ensuring the CLI input wins.

## Summary

- **Trivy uses Viper** to load YAML configuration files via the `--config` flag, defined in [`pkg/flag/global_flags.go`](https://github.com/aquasecurity/trivy/blob/main/pkg/flag/global_flags.go) and initialized in [`pkg/commands/app.go`](https://github.com/aquasecurity/trivy/blob/main/pkg/commands/app.go).
- **Default location** is [`trivy.yaml`](https://github.com/aquasecurity/trivy/blob/main/trivy.yaml) in the current directory; custom paths require the `--config` flag.
- **Validation** follows the JSON schema in [`schema/trivy-config.json`](https://github.com/aquasecurity/trivy/blob/main/schema/trivy-config.json).
- **Generation** of starter files is available via `trivy config init` (implemented in [`pkg/commands/artifact/run.go`](https://github.com/aquasecurity/trivy/blob/main/pkg/commands/artifact/run.go)).
- **CLI flags override** file settings, allowing flexible per-run adjustments while maintaining baseline configurations.

## Frequently Asked Questions

### What is the default name for the Trivy config file?

Trivy automatically looks for a file named **[`trivy.yaml`](https://github.com/aquasecurity/trivy/blob/main/trivy.yaml)** in the current working directory. If this file exists, Trivy loads it automatically without requiring the `--config` flag.

### Does Trivy support config file formats other than YAML?

According to the source code in [`pkg/commands/app.go`](https://github.com/aquasecurity/trivy/blob/main/pkg/commands/app.go) and the schema location at [`schema/trivy-config.json`](https://github.com/aquasecurity/trivy/blob/main/schema/trivy-config.json), Trivy specifically expects **YAML** format. While Viper supports multiple formats, Trivy’s implementation explicitly configures YAML parsing for configuration files.

### How do I validate my Trivy configuration file?

Trivy validates configuration against the JSON schema located at [`schema/trivy-config.json`](https://github.com/aquasecurity/trivy/blob/main/schema/trivy-config.json) in the repository. If your file contains invalid YAML or unsupported keys, the `initConfig` function in [`pkg/commands/app.go`](https://github.com/aquasecurity/trivy/blob/main/pkg/commands/app.go) returns a loading error with specific details about the parsing failure.

### Will command-line flags override settings in the config file?

**Yes.** Trivy binds all flags to the same Viper instance after loading the configuration file. This means any flag you pass on the command line will override the corresponding value in your [`trivy.yaml`](https://github.com/aquasecurity/trivy/blob/main/trivy.yaml) file, allowing you to keep default settings while making exceptions for specific scans.