+0
日增长
+8
周增长
+20
月增长
30,508
stars
2,232
forks
255
watchers
1,055
prs
938
issues
35
releases
README
Viper v2 Feedback
Viper is heading towards v2 and we would love to hear what _you_ would
like to see in it. Share your thoughts here:
https://forms.gle/R6faU74qPRPAzchZ9
Thank you!
!viper logo
!Go Version
Go configuration with fangs!
Many Go projects are built using Viper including:
Hugo
EMC RexRay
Imgur’s Incus
Nanobox/Nanopack
Docker Notary
BloomApi
doctl
Clairctl
Mercure
Meshery
Bearer
Coder
Vitess
Install
shell
go get github.com/spf13/viper
NOTE Viper uses Go Modules to manage dependencies.
Why use Viper?
Viper is a complete configuration solution for Go applications including
12-Factor apps. It is designed to
work within any application, and can handle all types of configuration needs
and formats. It supports:
setting defaults
setting explicit values
reading config files
dynamic discovery of config files across multiple locations
reading from environment variables
reading from remote systems (e.g. Etcd or Consul)
reading from command line flags
reading from buffers
live watching and updating configuration
aliasing configuration keys for easy refactoring
Viper can be thought of as a registry for all of your applications'
configuration needs.
Putting Values in Viper
Viper can read from multiple configuration sources and merges them together
into one set of configuration keys and values.
Viper uses the following precedence for merging:
explicit call to Set
flags
environment variables
config files
external key/value stores
defaults
NOTE Viper configuration keys are case insensitive.
Reading Config Files
Viper requires minimal configuration to load config files. Viper currently supports:
JSON
TOML
YAML
INI
envfile
Java Propeties
A single Viper instance only supports a single configuration file, but multiple
paths may be searched for one.
Here is an example of how to use Viper to search for and read a configuration
file. At least one path should be provided where a configuration file is
expected.
go
// Name of the config file without an extension (Viper will intuit the type
// from an extension on the actual file)
viper.SetConfigName("config")
// Add search paths to find the file
viper.AddConfigPath("/etc/appname/")
viper.AddConfigPath("$HOME/.appname")
viper.AddConfigPath(".")
// Find and read the config file
err := viper.ReadInConfig()
// Handle errors
if err != nil {
panic(fmt.Errorf("fatal error config file: %w", err))
}
You can handle the specific case where no config file is found.
go
var fileLookupError viper.FileLookupError
if err := viper.ReadInConfig(); err != nil {
if errors.As(err, &fileLookupError) {
// Indicates an explicitly set config file is not found (such as with
// using viper.SetConfigFile) or that no config file was found in
// any search path (such as when using viper.AddConfigPath)
} else {
// Config file was found but another error was produced
}
}
// Config file found and successfully Top issues
#1777Unclear doc11 comments · 2024-03-03#2095Move watcher initilization in Watch Config out of goroutine and panic on failure instead of os.Exit8 comments · 2025-11-21#2006Document the new file search API5 comments · 2025-03-26#1855Deprecate the global Viper instance3 comments · 2024-06-05#2161Expose resolved value provenance and the effective environment variable name1 comments · 2026-10-12#772Viper 21 comments · 2019-09-27#1755Call for testers0 comments · 2024-02-09#1046[RFC] Config provider mechanism0 comments · 2020-12-10
Discussions
#2148How can an explicitly empty environment variable override a default? (worked example)1 comments · 2026-09-05#2134[removed]0 comments · 2026-06-10#2108Changenotes — free AI changelog generator for viper0 comments · 2026-03-17#2085Error when running the make lint command1 comments · 2025-10-14#2049Will there be a new release soon?2 comments · 2025-08-21#2037How do you unmarshal environment variables _N_ directly to slice?0 comments · 2025-07-20#2034usage of gopkg.in/yaml.v3 is conflicting with go.yaml.in/yaml/v31 comments · 2025-07-15#2023为什么这个解析报错0 comments · 2025-06-06
Latest release
v1.21.0 v1.21.0 2025-09-08What's Changed Enhancements 🚀 Add support for flags pflag.BoolSlice, pflag.UintSlice and pflag.Float64Slice by @nmvalera in https://github.com/spf13/viper/pull/2015 feat: use maintained yaml library by @sagikazarmark in https://github.com/spf13/viper/pull/2040 Bug Fixes 🐛 fix(config): get config type from v.configType or config file ext by @GuillaumeBAECHLER in https://github.com/spf13/viper/pull/2003 fix: config type check when loading any config by @sagikazarmark in https://github.com/spf13/viper/pull/2007 Dependency Updates ⬆️ Update dependencies by @sagikazarmark in https:/