Go Viper configuration library (github.com/spf13/viper). Use when working with config file reading (SetConfigName, AddConfigPath, ReadInConfig), setting defaults, environment variable binding (SetEnvPrefix, AutomaticEnv, BindEnv), unmarshaling to structs (Unmarshal, UnmarshalKey, mapstructure tags), or any spf13/viper configuration management.
Viper is Go's most popular configuration library. It handles config files, environment variables, defaults, and remote config stores with a unified API.
viper.Set() - explicit runtime overridesviper.SetDefault() - defaults// Basic setup
viper.SetConfigName("config") // filename without extension
viper.SetConfigType("yaml") // explicit format
viper.AddConfigPath(".") // search current dir
viper.AddConfigPath("$HOME/.myapp") // search home dir
// Set defaults before reading
viper.SetDefault("server.port", 8080)
// Read config
if err := viper.ReadInConfig(); err != nil {
if _, ok := err.(viper.ConfigFileNotFoundError); ok {
// Config file not found; use defaults
} else {
return fmt.Errorf("config error: %w", err)
}
}
// Get values
host := viper.GetString("server.host")
port := viper.GetInt("server.port")
debug := viper.GetBool("debug")
// Unmarshal to struct
var config Config
viper.Unmarshal(&config)
viper.UnmarshalKey("server", &config.Server)
server.PORT and server.port are the sameAPP_PORT differs from app_portserver.host maps to YAML server: { host: ... }Detailed documentation for each feature area:
references/core-config.md - Config files, paths, defaults, reading, multiple configsreferences/environment-vars.md - Env binding, prefixes, key replacers, AutomaticEnvreferences/unmarshaling.md - Structs, mapstructure tags, type getters, custom typesreferences/advanced-features.md - Watching changes, remote config, writing configs// Main config
viper.SetConfigName("config")
viper.ReadInConfig()
// Separate secrets file
secretsViper := viper.New()
secretsViper.SetConfigName("secrets")
secretsViper.AddConfigPath(".")
secretsViper.ReadInConfig()
viper.SetEnvPrefix("MYAPP") // MYAPP_SERVER_PORT
viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
viper.AutomaticEnv()