Viper is a complete configuration solution for Go applications. It is designed to work within applications and can handle a wide range of configuration needs and formats.

Version Note

This article is based on Viper v1.x and has been reviewed against the API, official documentation, and corresponding source code of Viper v1.21.0. Support for configuration formats, error types, and some API behaviors may change between Viper versions. In practice, always refer to the official documentation for the version used by your project.

Viper

Because the viper library README is already very comprehensive, this article organizes its core content and supplements it with usage notes and engineering practices for the current version.

Installation

This article uses Viper v1.21.0. To ensure that the examples behave exactly as described, explicitly pin the version in your project:

go get github.com/spf13/viper@v1.21.0

After running the command, Go Modules records the Viper dependency version in go.mod. In team projects, commit both go.mod and go.sum to version control so that development environments and CI/CD pipelines use the same dependency versions.

If you want to upgrade Viper, first review API changes, supported configuration formats, and behavioral differences in the target release before updating the dependency version.

What Is Viper?

Viper is a complete configuration solution for Go applications, including Twelve-Factor App-style applications. It is designed to work within applications and supports a wide variety of configuration requirements and formats. Its features include:

• Setting default values
• Reading configuration from formats such as JSON, TOML, YAML, INI, envfile, and Java Properties
• Watching and re-reading configuration files optionally
• Reading from environment variables
• Reading from remote configuration systems such as etcd or Consul and watching for configuration changes
• Reading from command-line flags
• Reading configuration from an io.Reader
• Explicitly setting configuration values

Note

Supported configuration formats may change between Viper versions. Always refer to the official documentation for the version you are using.

Why Choose Viper?

When building modern applications, you generally do not want to spend much of your time handling different configuration sources and formats. Instead, you want to focus on business logic. Viper exists to provide a unified way to manage those configuration sources.

Viper can perform the following tasks for you:

1. Locate, load, and deserialize configuration files in formats such as JSON, TOML, YAML, INI, envfile, and Java Properties.
2. Define default values for configuration keys.
3. Override specific configuration values through command-line flags.
4. Provide an alias system so configuration keys can be renamed without breaking existing code.
5. Merge values from different configuration sources according to a fixed precedence order.

Viper reads configuration using the following precedence. Each item has higher priority than the items below it:

1. Values explicitly set with Set
2. Command-line flags
3. Environment variables
4. Configuration files
5. Remote key/value stores
6. Default values

Important: Viper configuration keys are case-insensitive by default.

Storing Values in Viper

Setting Default Values

A good configuration system should support default values. A configuration key does not have to define a default, but defaults are useful when no value is provided through a configuration file, environment variable, remote configuration source, or command-line flag.

The following examples assume that Viper has already been imported:

import "github.com/spf13/viper"

For example:

viper.SetDefault("ContentDir", "content")
viper.SetDefault("LayoutDir", "layouts")
viper.SetDefault(
	"Taxonomies",
	map[string]string{
		"tag":      "tags",
		"category": "categories",
	},
)

Reading Configuration Files

Viper needs to know where the configuration file is located, or which directories it should search.

Viper can search multiple paths, but a single Viper instance typically reads one configuration file during a configuration load. Viper does not define configuration search directories automatically; the application must specify them explicitly.

There are usually two ways to locate a configuration file:

1. Specify the full path to the configuration file directly.
2. Specify the configuration file name and add multiple search directories.

It is generally better not to mix these two approaches in the same example.

Option 1: Specify the Configuration File Directly

If you already know the full path to the configuration file, use SetConfigFile:

viper.SetConfigFile("./config.yaml")

if err := viper.ReadInConfig(); err != nil {
	return err
}

SetConfigFile explicitly specifies the file path, file name, and extension.

In this case, you do not need to call:

viper.SetConfigName(...)
viper.AddConfigPath(...)

For example:

viper.SetConfigFile("/etc/myapp/config.yaml")

if err := viper.ReadInConfig(); err != nil {
	return err
}

If the configuration file already has an extension such as .yaml or .json, Viper can usually determine the format from the extension, so there is no need to call SetConfigType separately.

Option 2: Let Viper Search for the Configuration File

If you want Viper to search multiple directories for the configuration file, use SetConfigName together with AddConfigPath:

viper.SetConfigName("config")

viper.AddConfigPath("/etc/appname/")
viper.AddConfigPath("$HOME/.appname")
viper.AddConfigPath(".")

if err := viper.ReadInConfig(); err != nil {
	return err
}

Here:

viper.SetConfigName("config")

specifies the configuration file name as config, without an extension.

Viper searches the directories added through AddConfigPath for a matching configuration file.

What SetConfigType Does

SetConfigType is mainly used when the configuration source itself does not provide file-extension information, for example:

• Configuration files without an extension
• Configuration read from an io.Reader
• Some remote configuration sources

For example, consider a normal configuration file with no extension:

myappconfig

You can explicitly tell Viper to parse it as YAML:

// The file has no extension, so explicitly tell Viper to parse it as YAML.
viper.SetConfigFile("./myappconfig")
viper.SetConfigType("yaml")

if err := viper.ReadInConfig(); err != nil {
	return err
}

Unix hidden files such as .bashrc, which begin with . and may not have a conventional extension, can also use SetConfigType to specify the format. This example uses myappconfig to avoid mixing the concepts of "no extension" and "hidden file."

If the configuration file is already:

config.yaml

you generally do not need to additionally set:

viper.SetConfigType("yaml")

Handling Configuration File Read Errors

This article is specifically based on Viper v1.21.0. In this version, when a configuration file searched through SetConfigName + AddConfigPath cannot be found, you can inspect the public error type viper.ConfigFileNotFoundError.

Modern Go code can use errors.As to handle this error:

package main

import (
	"errors"
	"fmt"

	"github.com/spf13/viper"
)

func loadConfig() error {
	viper.SetConfigName("config")
	viper.AddConfigPath(".")

	if err := viper.ReadInConfig(); err != nil {
		var notFoundError viper.ConfigFileNotFoundError

		if errors.As(err, &notFoundError) {
			// The configuration file was not found.
			// If the configuration file is optional, you may choose to ignore the error here.
			return nil
		}

		// The configuration file exists, but another error occurred while reading or parsing it.
		return fmt.Errorf("failed to read configuration file: %w", err)
	}

	return nil
}

You need to distinguish between two cases:

• The configuration file was not found.
• The configuration file was found, but reading or parsing failed.

Keep in mind that Viper error types may change in later versions. The example above targets v1.21.0; after upgrading the dependency, refer to the corresponding official documentation and source code.

Also note that explicitly pointing SetConfigFile at a specific nonexistent file may produce different errors across versions than searching for a missing file through search paths. Therefore, do not treat every ReadInConfig error as a ConfigFileNotFoundError.

Multiple Configuration Files with the Same Name but Different Formats

Suppose the directory contains both:

./conf/config.json
./conf/config.yaml

and the code is:

viper.SetConfigName("config")
viper.AddConfigPath("./conf")

In this situation, business logic should not depend on Viper's internal extension search order to determine which file is loaded.

A more reliable approach is to ensure that each environment contains only one valid configuration file with that base name, or explicitly specify the file:

viper.SetConfigFile("./conf/config.yaml")

This makes the behavior unambiguous and easier to maintain.

Writing Configuration Files

Reading configuration from files is common, but sometimes an application also needs to write runtime configuration back to a file.

Viper provides the following methods:

• WriteConfig: Writes the current configuration to the already determined configuration file and overwrites the original file.
• SafeWriteConfig: Writes to the determined configuration file, but does not overwrite the target if it already exists.
• WriteConfigAs: Writes the current configuration to a specified file path and overwrites the file if it already exists.
• SafeWriteConfigAs: Writes the current configuration to a specified file path and does not overwrite the file if it already exists.

In general, methods with the Safe prefix are intended to prevent accidental overwriting of existing configuration files.

Viper v1.21.0 Prerequisites

• WriteConfig() first determines the current configuration file location. If SetConfigFile has been used, that path can be used directly; otherwise, Viper searches based on the configured file name and search paths. If the target file cannot be determined, the method returns an error.
• SafeWriteConfig() does not behave exactly like WriteConfig(). In v1.21.0, it requires at least one configuration directory to have been set through AddConfigPath, and it constructs a new file path from configName and configType. In practice, you should explicitly set SetConfigName, SetConfigType, and AddConfigPath together.
• WriteConfigAs(path) and SafeWriteConfigAs(path) receive the target path directly, so they do not depend on a previously discovered configuration file. However, Viper must still be able to determine the serialization format from either the target file extension or SetConfigType.
• SafeWriteConfig* does not overwrite an existing target file.

Example:

if err := viper.WriteConfig(); err != nil {
	fmt.Println("failed to write configuration:", err)
}

if err := viper.SafeWriteConfig(); err != nil {
	fmt.Println("failed to safely write configuration:", err)
}

if err := viper.WriteConfigAs("/path/to/my/.config"); err != nil {
	fmt.Println("failed to write configuration to the specified file:", err)
}

if err := viper.SafeWriteConfigAs("/path/to/my/.other_config"); err != nil {
	fmt.Println("failed to safely write configuration to the specified file:", err)
}

For SafeWriteConfig(), it is recommended to explicitly configure the information required for writing:

viper.SetConfigName("config")
viper.SetConfigType("yaml")
viper.AddConfigPath("./conf")

if err := viper.SafeWriteConfig(); err != nil {
	fmt.Println("failed to safely write configuration:", err)
}

WriteConfigAs and SafeWriteConfigAs allow the target path to be specified directly:

viper.WriteConfigAs("./conf/config.yaml")
viper.SafeWriteConfigAs("./conf/config.yaml")

Watching and Reloading Configuration Files

Viper can watch configuration files for changes and re-read them when they are modified.

When using configuration watching, configure the file path before calling WatchConfig(). It is also recommended to register the callback before starting the watcher.

Example:

package main

import (
	"fmt"

	"github.com/fsnotify/fsnotify"
	"github.com/spf13/viper"
)

func main() {
	viper.SetConfigName("config")
	viper.AddConfigPath(".")

	if err := viper.ReadInConfig(); err != nil {
		panic(err)
	}

	viper.OnConfigChange(func(e fsnotify.Event) {
		fmt.Println("Config file changed:", e.Name)
	})

	viper.WatchConfig()

	select {}
}

Production Practice Recommendation

The select {} above is only used to keep the demo program running. It permanently blocks the current goroutine and provides no shutdown mechanism. In real applications, graceful shutdown should usually be implemented with context.Context, os.Signal, or the application's own lifecycle management rather than relying on permanent blocking.

One important point requires special attention:

Viper being able to re-read a configuration file does not mean that every component already initialized in the application will automatically apply the new configuration.

For example:

• Database connection pool size
• HTTP server timeouts
• Third-party client configuration
• Logging component settings

If these objects were initialized from the old configuration, whether they support dynamic changes must be handled by the application code itself.

Therefore, "configuration file hot reload" and "automatic hot reload of the entire application" are not the same thing.

Reading Configuration from io.Reader

Viper defines many configuration sources in advance, such as:

• Files
• Environment variables
• Command-line flags
• Remote K/V stores

In addition, configuration can also be read from an io.Reader.

In this case, there is no file extension for Viper to use when determining the configuration format, so you usually need to call SetConfigType first.

Note

ReadConfig replaces the current configuration-file data in the Viper instance with the newly read configuration. If you want to merge new configuration content into existing configuration, use MergeConfig. If the new configuration source is already a map[string]any, use MergeConfigMap.

Example:

package main

import (
	"bytes"
	"fmt"

	"github.com/spf13/viper"
)

func main() {
	viper.SetConfigType("yaml")

	var yamlExample = []byte(`
Hacker: true
name: steve
hobbies:
  - skateboarding
  - snowboarding
  - go
clothing:
  jacket: leather
  trousers: denim
age: 35
eyes: brown
beard: true
`)

	if err := viper.ReadConfig(bytes.NewBuffer(yamlExample)); err != nil {
		panic(err)
	}

	name := viper.GetString("name")
	fmt.Println(name)
}

Output:

steve

Compared with directly using:

viper.Get("name")

if you know that the configuration value is a string, using:

viper.GetString("name")

makes the intent of the code clearer.

Explicit Overrides

In addition to reading configuration from files, environment variables, and command-line flags, you can also override configuration values directly in application logic:

viper.Set("Verbose", true)
viper.Set("LogFile", LogFile)

Values set through Set have the highest configuration priority.

For example:

viper.SetDefault("server.port", 8080)
viper.Set("server.port", 9090)

fmt.Println(viper.GetInt("server.port"))

Output:

9090

Registering and Using Aliases

Aliases allow multiple configuration keys to reference the same configuration value.

For example:

viper.RegisterAlias("loud", "verbose")

viper.Set("verbose", true)

fmt.Println(viper.GetBool("loud"))
fmt.Println(viper.GetBool("verbose"))

Output:

true
true

After creating an alias with:

viper.RegisterAlias("loud", "verbose")

loud and verbose reference the same configuration item.

Therefore:

viper.Set("loud", false)

also affects:

viper.GetBool("verbose")

Using Environment Variables

Viper fully supports environment variables, making it well suited to Twelve-Factor App-style applications.

Common environment-variable-related APIs include:

• AutomaticEnv()
• BindEnv(string...) error
• SetEnvPrefix(string)
• SetEnvKeyReplacer(*strings.Replacer)
• AllowEmptyEnv(bool)

When using environment variables, keep the following in mind:

Environment variable names are case-sensitive.

SetEnvPrefix

SetEnvPrefix lets you apply a common prefix to environment variable names.

For example:

viper.SetEnvPrefix("spf")

When Viper automatically derives an environment variable name from a configuration key, it uses a name similar to:

SPF_ID

BindEnv

BindEnv accepts one or more string arguments.

The first argument is the configuration key in Viper.

For example:

if err := viper.BindEnv("id"); err != nil {
	return err
}

If you do not explicitly provide an environment variable name, Viper derives it according to rules involving:

• The configuration key
• SetEnvPrefix
• SetEnvKeyReplacer

You can also explicitly bind an environment variable:

if err := viper.BindEnv("database.host", "DB_HOST"); err != nil {
	return err
}

You can also bind multiple candidate environment variables to the same configuration key:

if err := viper.BindEnv(
	"database.host",
	"DB_HOST",
	"DATABASE_HOST",
); err != nil {
	return err
}

Viper checks the corresponding environment variables in binding order.

Environment Variables Are Resolved Dynamically on Every Read, Not Cached by BindEnv

There is an important behavior to understand when working with environment variables:

Viper does not permanently cache the environment variable value when BindEnv is called.

When reading a configuration value, for example:

viper.Get("id")

Viper checks the corresponding environment variable again.

Therefore, if the environment variable changes while the program is running, later Get calls may read the new value.

AutomaticEnv

AutomaticEnv makes Viper automatically check the corresponding environment variable when Get is called.

For example:

viper.SetEnvPrefix("myapp")
viper.AutomaticEnv()

port := viper.GetInt("port")

At this point, Viper attempts to read the corresponding environment variable.

Note:

AutomaticEnv() is not equivalent to copying all operating-system environment variables into Viper's configuration map in advance.

Its primary purpose is to dynamically check environment variables when a configuration key is read.

Therefore, when using it together with APIs such as:

viper.Unmarshal(...)

you should not assume that every environment variable readable through AutomaticEnv will automatically participate in struct unmarshaling as a configuration key.

The reason is that AutomaticEnv mainly performs dynamic environment lookups when methods such as Get are called for configuration keys Viper already knows about. It does not proactively scan every operating-system environment variable and register all environment variable names as Viper configuration keys. Unmarshal, on the other hand, mainly deserializes from Viper's known key set. Therefore, calling only AutomaticEnv() does not guarantee that arbitrary environment-variable fields will automatically populate the target struct.

For configuration values that need to participate in Unmarshal, explicitly establish the corresponding configuration keys. For example:

viper.SetDefault("server.port", 8080)

or:

viper.BindEnv("server.port", "SERVER_PORT")

SetEnvKeyReplacer

Environment variables usually use underscores:

DATABASE_HOST

while application configuration keys may use dotted notation:

database.host

In this case, you can use:

strings.NewReplacer(".", "_")

to transform configuration keys into environment-variable format.

For example:

package main

import (
	"fmt"
	"os"
	"strings"

	"github.com/spf13/viper"
)

func main() {
	viper.SetEnvKeyReplacer(
		strings.NewReplacer(".", "_"),
	)

	viper.AutomaticEnv()

	os.Setenv("DATABASE_HOST", "127.0.0.1")

	host := viper.GetString("database.host")

	fmt.Println(host)
}

Output:

127.0.0.1

AllowEmptyEnv

By default, if an environment variable exists but contains an empty string, Viper treats it as unset and continues checking the next configuration source.

If you want an empty environment variable to be treated as a valid configuration value, call:

viper.AllowEmptyEnv(true)

Environment Variable Example

The following is a complete, runnable example:

package main

import (
	"fmt"
	"os"

	"github.com/spf13/viper"
)

func main() {
	viper.SetEnvPrefix("spf")

	if err := viper.BindEnv("id"); err != nil {
		panic(err)
	}

	os.Setenv("SPF_ID", "13")

	id := viper.Get("id")

	fmt.Println(id)
}

Output:

13

In real applications, environment variables are usually provided by:

• The shell
• Docker
• Kubernetes
• CI/CD systems
• Cloud platforms

before the program starts, rather than being set in business logic with:

os.Setenv(...)

os.Setenv is used here only for demonstration purposes.

Recommended: Use an Independent Viper Instance

For simple programs, you can use the package-level API directly:

viper.Set(...)
viper.Get(...)

However, in medium-to-large projects, unit tests, or applications that manage multiple configuration sets, it is better to create an independent Viper instance:

v := viper.New()

v.SetConfigName("config")
v.AddConfigPath(".")

if err := v.ReadInConfig(); err != nil {
	return err
}

port := v.GetInt("server.port")

Compared with using the global viper instance, this approach is better for:

• Reducing coupling caused by global state
• Writing unit tests
• Managing multiple configuration sets
• Preventing different modules from polluting one another's configuration

Concurrency Safety Note

Viper explicitly states that concurrent reads and writes on the same Viper instance are not safe. Concurrent operations such as Get() and Set() may cause a panic.

If configuration remains unchanged after application startup and the business layer only performs reads, the risk is relatively low. However, once WatchConfig() is used to reload configuration dynamically, configuration updates and business reads may happen concurrently. In that case, synchronize access yourself, for example with sync.RWMutex, or use Unmarshal after a configuration change to produce a new configuration struct snapshot and expose that immutable snapshot to the business layer.

Summary

Viper's core role can be summarized as follows:

Read from multiple configuration sources through a unified interface
        ↓
Merge configuration according to precedence
        ↓
Expose configuration to business code through a unified API

A common configuration precedence is:

Set
 ↓
Flag
 ↓
Environment
 ↓
Config File
 ↓
Remote K/V Store
 ↓
Default

In real projects, pay particular attention to the following points:

1. SetConfigFile and SetConfigName + AddConfigPath are two different ways to locate configuration files and should not be mixed in the same example.
2. Handle errors returned by APIs such as ReadInConfig, ReadConfig, and BindEnv.
3. WatchConfig only watches and re-reads configuration; it does not automatically reinitialize business components in the application.
4. AutomaticEnv mainly checks environment variables dynamically when configuration keys are read. It should not be interpreted as loading every system environment variable into Viper.
5. For medium-to-large projects, prefer creating an independent configuration instance with viper.New().
6. Supported configuration formats and error types may change between Viper versions. Always refer to the official documentation for the dependency version used by your project.