Viper
A Go library for loading and merging application configuration from files, env vars, flags, and more.
- Stars
- 30.5k
- Forks
- 2.2k
- Licence
- MIT
- Language
- Go
- Last update
- 10 months ago
- Type
- Library
What it is
Viper is a Go library that lets a program read its settings from many places at once, such as config files, environment variables, command-line flags, and remote key-value stores. It merges these sources using a set precedence order, so a value set in code can override a flag, which can override an environment variable, and so on. Developers use it so they do not have to write separate loading code for each source.
- Load a YAML, JSON, or TOML config file from several search paths, falling back to defaults
- Override a config value with an environment variable using a prefix such as SPF_ID
- Bind command-line flags so they feed into the same configuration keys
- Watch a config file and run a callback when it changes
Great for
- Go developers building command-line tools or servers that need configuration
- Projects that must read settings from both files and environment variables (12-factor style apps)
- Teams that use Cobra or pflag for flags and want them tied into the same config
- Applications that need config files to reload while running
Not ideal for
- Non-Go projects, since the library is written for Go only
- Very small programs where reading one file or a few environment variables is enough, because the library adds dependencies and concepts
- Users looking for an end-user app rather than a code library
How to get it
- 1
Install with a package manager
You'll need: Go (the README notes Go Modules are used; the badge indicates Go 1.23 or newer)
Install the library into a Go module
go get github.com/spf13/viper - 2
Run it
- Install the library with go get in your Go module.
- Call viper.SetConfigName and viper.AddConfigPath to tell it where to look for a config file.
- Call viper.ReadInConfig and handle any error it returns.
- Read values with viper.Get or typed getters such as viper.GetBool.
- 3
Get the most out of it
- Use viper.SetDefault so the program still runs when a key is missing.
- Bind environment variables with SetEnvPrefix and AutomaticEnv to override file settings in deployments.
- Connect command-line flags with BindPFlag so flags take priority over files.
- Use WatchConfig with OnConfigChange to apply config edits without restarting the server.
Downloads
Strengths
- Supports many formats including JSON, TOML, YAML, INI, envfile, and Java properties
- Has a clear, documented precedence order for merging sources
- Widely used; the README lists projects such as Hugo and doctl that rely on it
Trade-offs
- Configuration keys are case insensitive, while environment variables are case sensitive, which can cause confusion
- A single Viper instance supports only one config file
How it compares
| Project | Stars | Type | Level | Updated | Best for |
|---|---|---|---|---|---|
| viper (this) | 30.5k | Library | intermediate | 10 months ago | Go developers building command-line tools or servers that need configuration |
| godotenv | 10.7k | Library | beginner | 3 months ago | Go developers who want local configuration kept in a .env file |
Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.