Viper

Viper is a configuration management library for Go that unifies every common configuration source — command-line flags, environment variables, JSON/TOML/YAML/INI/envfile/Java-properties files, remote key/value stores like etcd and Consul, and explicit in-code overrides — behind a single, consistent get/set API. Rather than forcing an application to wire up separate parsers for each source, Viper applies a fixed precedence order (explicit Set calls, flags, env vars, config file, remote store, defaults) so callers can just ask for a value by key and get the right one regardless of where it came from.

It is designed as the natural companion to Cobra (both maintained by the same author), binding directly to pflag-based command flags, but it works equally well standalone. Beyond static lookups, Viper supports live config-file watching via fsnotify with change callbacks, key aliasing for painless refactors, and unmarshaling straight into structs or maps via mapstructure. It has been adopted by large Go projects including Hugo, Docker Notary, and DigitalOcean’s doctl, and remains one of the most widely used configuration libraries in the Go ecosystem.

What You Get

• A unified Get/GetString/GetInt/GetBool-style API that reads from any bound source transparently
• Automatic parsing of JSON, TOML, YAML, INI, envfile, and Java properties config files via pluggable internal codecs
• Live config-file watching with WatchConfig() and OnConfigChange() callbacks powered by fsnotify
• Struct and map unmarshaling built on github.com/go-viper/mapstructure/v2, including embedded-struct squashing and custom decode hooks
• Remote key/value store support (etcd, etcd3, Consul, Firestore, NATS) via a separate viper/remote submodule, with optional GPG-encrypted values through crypt
• First-class pflag/Cobra flag binding through BindPFlag/BindPFlags, plus a pluggable FlagValue/FlagValueSet interface for other flag libraries

Common Use Cases

• Loading a CLI application’s settings from a config file that can be overridden by flags and environment variables, in a well-defined precedence order
• Building Cobra-based CLIs (doctl-style) where subcommand flags need to flow into the same configuration object as file- and env-based settings
• Hot-reloading a long-running service’s configuration when its config file changes on disk, without a restart
• Centralizing configuration for multiple deployment environments by combining defaults, a checked-in config file, and environment-variable overrides for secrets
• Distributing configuration across a fleet of services via a shared etcd or Consul key, optionally GPG-encrypted

Under The Hood

Architecture

Viper centers on a single Viper struct (viper.go, ~2,170 lines) that owns per-source state — flags, env bindings, the parsed config-file map, remote-provider results, defaults, and explicit overrides — and resolves a requested key by walking those sources in precedence order (override > flag > env > config > key/value store > default) inside Get. A package-level v *Viper singleton (initialized in init()) backs the free-function API so viper.Get(...) and NewViper().Get(...) share the same code path. File discovery and format detection are delegated to a Finder interface (finder.go) operating over an afero.Fs abstraction rather than the OS filesystem directly, which is what lets tests and the viper.ReadConfig(io.Reader) path share logic with real file loads. Config-format parsing is isolated behind per-format codecs under internal/encoding/{json,toml,yaml,dotenv}, each implementing a small Codec interface, and encoding.go picks the right one from the file extension or an explicit SetConfigType call — so what breaks if you swap the YAML backend (as the project itself just did, moving to go.yaml.in/yaml/v3) is isolated to one codec file, not the whole library.

Tech Stack

Written in Go 1.23+, with a go.mod-declared dependency set that stays deliberately narrow: fsnotify for filesystem watch events, go-viper/mapstructure/v2 for reflection-based struct decoding, pelletier/go-toml/v2 and go.yaml.in/yaml/v3 for format parsing, spf13/afero for the virtual filesystem layer, spf13/cast for type coercion in the Get<Type> accessors, and spf13/pflag for POSIX-style flag binding. Remote key/value store support (etcd/etcd3/Consul/Firestore/NATS, via sagikazarmark/crypt) lives in a separate remote/ Go submodule with its own go.mod, keeping those heavier network dependencies out of the default import graph for consumers who only need local config files. The project also ships a Nix flake (flake.nix/flake.lock) for a reproducible contributor dev environment alongside a plain Makefile.

Code Quality

The root package has an extensive test suite — viper_test.go alone contains roughly 80 test functions covering precedence resolution, aliasing, sub-config extraction, remote providers, and edge cases in key delimiting — using the standard testing package with testify for assertions, plus dedicated _test.go files per concern (flags_test.go, finder_test.go, overrides_test.go, encoding_test.go). Each internal codec package carries its own codec_test.go. Errors are modeled as typed values (errors.go defines error types like FileLookupError and ConfigParseError, checked via errors.As in the README’s documented patterns) rather than raw string errors, and CI runs across js/wasm and aix/ppc64 build targets in addition to the standard matrix, which is unusually broad platform coverage for a configuration library. A make lint/make fmt pair enforces style, and the CI workflow gates on both build and lint jobs.

API Design Viper’s defining design choice is precedence-based key resolution over a case-insensitive, dot-delimited key space — callers write GetString("datastore.metric.host") once and get the right value whether it came from a flag, an env var, or a nested YAML block, without writing merge logic themselves. The tradeoff is an explicitly documented one: Viper does not deep-merge complex values (a fully-overridden key replaces the whole subtree), and concurrent read/write access is the caller’s responsibility to synchronize, both called out directly in the README rather than silently assumed. The package-level singleton keeps the zero-config case trivially easy (viper.Get(...) works with no setup) while viper.New() supports isolated instances for testing or multi-config scenarios — the README explicitly recommends the latter as best practice despite defaulting the former, which is an honest acknowledgment of a design tension rather than a hidden gotcha.