Intended Audience

This page describes who envconfig is designed for and what background you need to get the most out of it. Understanding the intended audience helps you decide whether envconfig fits your project and how to approach the rest of the documentation.

Who envconfig is for

envconfig is built for Go developers who need a straightforward, low-friction way to configure their applications using environment variables. If you are writing a Go service, CLI tool, or any application that needs to read configuration from its environment, envconfig is designed with you in mind.

Assumed knowledge

To work effectively with envconfig, you should be comfortable with the following:

• Go fundamentals — You can define structs, work with packages, and run a Go program. You do not need advanced Go expertise.
• Environment variables — You understand what environment variables are and how to set them in a shell or deployment environment (for example, export PORT=8080).
• Basic struct usage in Go — envconfig maps environment variables onto struct fields, so you should be familiar with defining and instantiating structs.

You do not need prior experience with configuration libraries, reflection, or Go struct tags. envconfig introduces those concepts where relevant.

What problems envconfig solves for you

If you have ever written repetitive boilerplate like os.Getenv("APP_PORT") and then manually converted the result to an integer, checked for empty strings, or tried to set a default value — envconfig handles all of that for you automatically. It reads your environment variables and populates a typed Go struct in a single function call, so you can focus on your application logic instead of configuration plumbing.

envconfig is particularly well-suited for:

• Twelve-factor applications that treat configuration as environment — a common pattern in containerized and cloud-native deployments.
• Teams adopting Go who want configuration that is easy to audit, document, and override without changing source code.
• Developers who value simplicity and prefer a small, focused library over a large configuration framework.

Who this documentation assumes you are

The documentation on this site is written for an intermediate Go developer evaluating envconfig for the first time. The goal is to get you from zero to a working configuration-loading setup in minutes. Examples are self-contained and explained step by step. No prior knowledge of this library is required.

The following example shows what a typical envconfig user's workflow looks like — from defining a configuration struct to reading values from the environment. This is the kind of task envconfig is designed for.

Setting environment variables and loading them into a typed struct

export MYAPP_DEBUG=false
export MYAPP_PORT=8080
export MYAPP_USER=Kelsey
export MYAPP_RATE="0.5"
export MYAPP_TIMEOUT="3m"
export MYAPP_USERS="rob,ken,robert"
export MYAPP_COLORCODES="red:1,green:2,blue:3"

package main

import (
    "fmt"
    "log"
    "time"

    "github.com/kelseyhightower/envconfig"
)

type Specification struct {
    Debug      bool
    Port       int
    User       string
    Users      []string
    Rate       float32
    Timeout    time.Duration
    ColorCodes map[string]int
}

func main() {
    var s Specification
    err := envconfig.Process("myapp", &s)
    if err != nil {
        log.Fatal(err.Error())
    }
    format := "Debug: %v\nPort: %d\nUser: %s\nRate: %f\nTimeout: %s\n"
    _, err = fmt.Printf(format, s.Debug, s.Port, s.User, s.Rate, s.Timeout)
    if err != nil {
        log.Fatal(err.Error())
    }

    fmt.Println("Users:")
    for _, u := range s.Users {
        fmt.Printf("  %s\n", u)
    }

    fmt.Println("Color codes:")
    for k, v := range s.ColorCodes {
        fmt.Printf("  %s: %d\n", k, v)
    }
}

Expected output:

Debug: false
Port: 8080
User: Kelsey
Rate: 0.500000
Timeout: 3m0s
Users:
  rob
  ken
  robert
Color codes:
  red: 1
  green: 2
  blue: 3

Notice that you did not write any type conversion or error handling for individual fields — envconfig handled the conversion from string environment variables to bool, int, float32, time.Duration, []string, and map[string]int automatically. This is the core value the library provides to its intended users.

Once you understand who envconfig is for, the following pages provide the next steps:

• Getting started —<u> Install</u> envconfig and run your first configuration-loading program.
• Defining a configuration struct — Learn how to design the struct that envconfig will populate, including supported field types.
• Struct tag support — Understand how to customize field behavior with tags for defaults, required fields, and custom environment variable names.
• Custom decoders — Learn how to handle complex types that go beyond the built-in supported fields.
• Environment variable naming conventions — See how envconfig maps struct field names to environment variable names using the prefix you supply to envconfig.Process.