Viper
By spf13 and Viper contributors
Viper is a configuration management library for Go applications that reads settings from multiple sources — configuration files, environment variables, command-line flags, remote key-value stores, and in-code defaults — and merges them…
Definition
Viper is a configuration management library for Go applications that reads settings from multiple sources — configuration files, environment variables, command-line flags, remote key-value stores, and in-code defaults — and merges them into a single, consistently accessible set of values. It supports common file formats including JSON, TOML, YAML, and INI, and lets an application watch a configuration file for changes and reload automatically. Viper is used to centralize configuration handling in Go services and CLI tools, and is frequently paired with the Cobra command-line library.
Overview
Viper was built to solve a problem that grows with almost every Go application over time: configuration values tend to arrive from several different places — a checked-in config file, environment variables set by a deployment platform, command-line flags for local overrides, and hard-coded defaults for anything unset — and without a shared library, each project reinvents its own precedence rules and parsing logic for merging them. Viper standardizes that merging behavior so an application can ask for a single value, such as a database host, without knowing or caring which of those sources actually provided it. Mechanically, Viper maintains an internal key-value store and applies a fixed precedence order when resolving a requested key: explicit calls to `Set` in code take the highest priority, followed by command-line flags, environment variables, configuration file values, remote configuration systems such as etcd or Consul, and finally any defaults registered in code. It parses configuration files written in JSON, TOML, YAML, HCL, INI, and Java properties formats using format-specific parsers, and exposes values through typed getter functions like `GetString`, `GetInt`, and `GetBool`, as well as the ability to unmarshal configuration directly into a Go struct. An optional file-watching feature, built on the fsnotify library, lets an application detect changes to its configuration file at runtime and re-read the updated values without a restart. Viper differs from simpler approaches like reading environment variables directly with `os.Getenv` or parsing a single JSON file manually in that it unifies multiple source types under one API and a clear override order, removing the need for an application to hand-write that precedence logic itself. It is most often used alongside Cobra, where Viper binds a Cobra command's flags into its own configuration store so that a setting can be provided as either a flag or an environment variable and read through the same Viper call, though the two libraries have no hard dependency on one another and can be used independently. In practice, Viper is common in Go microservices, Kubernetes operators, and CLI tools that need to support configuration from a file in development and environment variables or flags in production or containerized environments. Its ability to unmarshal an entire configuration tree into a typed Go struct is often used to keep configuration access type-safe throughout an application rather than scattering string-keyed lookups across the codebase. A known trade-off is that Viper's global, singleton-style default instance can make configuration state harder to isolate in unit tests unless a project deliberately uses Viper's `New()` constructor to create scoped, independent instances instead of relying on the package-level default; some teams also find its many supported formats and sources add more surface area than a smaller project actually needs, in which case a narrower library focused solely on environment variables may be a better fit.
Key Features
- Merges configuration from files, env vars, flags, and remote stores
- Fixed precedence order for resolving conflicting configuration values
- Supports JSON, TOML, YAML, HCL, INI, and Java properties formats
- Typed getter functions and struct unmarshaling for configuration values
- Live configuration file watching and reloading via fsnotify
- Deep integration with Cobra for binding CLI flags to config keys
- Support for remote key-value configuration systems like etcd and Consul