Comprehensive Guide to Using Viper for Go Application Configuration

Viper is a powerful Go configuration library that supports multiple formats (JSON, TOML, YAML, HCL, INI, envfile, Java Properties) and sources, including default values, command‑line flags, environment variables, configuration files, remote key/value stores, and explicit overrides.

Why Choose Viper

Viper abstracts away configuration file formats, allowing developers to focus on building software. It can load, deserialize, set defaults, alias keys, and differentiate between user‑provided values and defaults.

Loading Priority

Explicit viper.Set values

Command‑line arguments

Environment variables

Configuration files

Remote key/value store

Default values

Reading Configuration into Viper

Viper offers several methods to ingest configuration:

Set default values with viper.SetDefault(key, value)

Read from configuration files using viper.SetConfigFile() or viper.AddConfigPath() combined with viper.SetConfigName()

Watch and hot‑reload files via viper.WatchConfig() and viper.OnConfigChange()

Read from an io.Reader with viper.ReadConfig()

Load environment variables using viper.AutomaticEnv() , viper.BindEnv() , viper.SetEnvPrefix() , and viper.SetEnvKeyReplacer()

Bind command‑line flags via the pflag package with viper.BindPFlag() or viper.BindPFlags()

Fetch remote configurations (e.g., Consul, etcd) by importing viper/remote and using viper.AddRemoteProvider() and viper.ReadRemoteConfig()

Retrieving Configuration Values

Use viper.Get(key) for generic values or type‑specific getters such as GetString , GetInt , GetBool , etc. Check existence with viper.IsSet(key) . Access nested keys with dot notation (e.g., viper.Get("server.ip") ) or retrieve sub‑trees via viper.Sub("server") .

Serialization and Deserialization

Deserialize the entire configuration into a struct with viper.Unmarshal(&cfg) or a specific key with viper.UnmarshalKey("password", &pwd) . Serialize all settings to a YAML string using yaml.Marshal(viper.AllSettings()) or write back to files with viper.WriteConfig() , SafeWriteConfig() , WriteConfigAs() , and SafeWriteConfigAs() .

Multiple Viper Instances

While Viper provides a singleton for simple use cases, you can create independent instances with viper.New() , each with its own configuration sources and values, useful for complex applications.

Best Practices

For small projects, use the default singleton instance. For medium to large projects, define a configuration struct and unmarshal Viper data into it, registering viper.OnConfigChange() callbacks to keep the struct in sync with live changes.