Viper for Go: Complete Guide with Examples

What is Viper and why do you need it?

Viper is one of the most popular libraries for configuration management in Go applications. It provides a universal and flexible way to work with settings that can come from various sources: configuration files (JSON, TOML, YAML, HCL, INI, envfile), environment variables, command-line flags, remote stores (etcd, Consul), and even default values set in code.

Why do you need Viper? In modern development, configuration is rarely static. An application may run in different environments (dev, staging, production), use different databases, API keys, and ports. Viper solves several key tasks:

• Hierarchical structure: allows nesting settings within each other (e.g., database.host).
• Source priority: clearly defines which source has higher priority (e.g., flags override environment variables).
• Automatic binding: can automatically bind environment variables to configuration keys.
• Multiple format support: no need to write parsers for each format.
• Type safety: provides methods to retrieve values with type conversion (GetInt, GetString, GetBool, etc.).

Viper is ideal for creating microservices, web applications, CLI utilities, and any other Go programs that require flexible configuration management.

Installing Viper

Viper is installed using the standard Go method — via the go get package manager. Make sure you have Go version 1.18 or higher installed.

go get github.com/spf13/viper

After running this command, Viper will be added to your go.mod file. To work with specific file formats (e.g., YAML), you may also need additional libraries, but Viper comes with built-in support for JSON, TOML, and YAML "out of the box". If you use go mod, dependencies will be pulled automatically.

Example import in code:

import (    "github.com/spf13/viper")

Quick Start: First Example with Viper

Let's write a simple program that reads configuration from a config.yaml file and prints a greeting.

Create a file config.yaml:

app:  name: "MyApp"  version: "1.0.0"server:  port: 8080

Now create a file main.go:

package main

import (    "fmt"    "log"    "github.com/spf13/viper")

func main() {    // Set the configuration file name    viper.SetConfigName("config")    // Set the file type    viper.SetConfigType("yaml")    // Add search paths    viper.AddConfigPath(".")

    // Read the configuration    if err := viper.ReadInConfig(); err != nil {        log.Fatalf("Error reading configuration: %s", err)    }

    // Get values    appName := viper.GetString("app.name")    appVersion := viper.GetString("app.version")    port := viper.GetInt("server.port")

    fmt.Printf("Application: %s (version %s) running on port %d", appName, appVersion, port)}

Run the program:

go run main.go

Output:

Application: MyApp (version 1.0.0) running on port 8080

This simple example demonstrates the basic mechanics: we tell Viper where to find the file, read it, and then extract values by keys.

Main Methods and Functions of Viper

Viper provides a rich API. Below we will cover 10 key methods with detailed descriptions and examples.

1. SetConfigName