envconfig

envconfig

A small, dependency-free Go library for loading configuration from environment variables directly into your structs.

It supports nested structs, prefixes, defaults, required fields, slices, maps, arrays, pointers, durations, and custom (un)marshalers. A helper is provided to read variables from a .env file.

• Zero dependencies
• Simple, tag-driven API
• Works with standard os.LookupEnv or a custom lookups
• Optional .env file loader (supports comments, export, quoting, inline comments)

Installation

go get github.com/struct0x/envconfig

Quick start

package main

import (
	"fmt"

	"github.com/struct0x/envconfig"
)

type HTTPServer struct {
	Env     string            `env:"ENV"`
	Host    string            `env:"HOST" envDefault:"127.0.0.1"`
	Port    int               `env:"PORT" envRequired:"true"`
	Enabled bool              `env:"ENABLED"`
	Tags    []string          `env:"TAGS"`     // "a,b,c" -> []string{"a","b","c"}
	Headers map[string]string `env:"HEADERS"`  // "k1=v1,k2=v2"
	DB      *DBConfig         `envPrefix:"DB"` // nil when no DB_* vars are set
}

func main() {
	var cfg HTTPServer

	// Use OS environment by default
	if err := envconfig.Read(&cfg); err != nil {
		panic(err)
	}

	fmt.Printf("%+v\n", cfg)
}

Example environment:

export PORT=8080
export ENABLED=true
export TAGS="alpha,beta"
export HEADERS="X-Req=abc,X-Trace=on"

Using a .env file

Use EnvFileLookup to source values from a .env file. Lines use KEY=VALUE, support comments and export statements, and handle quoted values with inline comments.

package main

import (
	"fmt"

	"github.com/struct0x/envconfig"
)

type App struct {
	Name string `env:"NAME" envDefault:"demo"`
	Port int    `env:"PORT" envRequired:"true"`
}

func main() {
	var cfg App

	if err := envconfig.Read(&cfg, envconfig.EnvFileLookup(".env")); err != nil {
		panic(err)
	}

	fmt.Printf("%+v\n", cfg)
}

Notes:

• If both the .env file and the OS define a key, the OS environment value wins.
• EnvFileLookup falls back to OS env if a file cannot be read.

Tags

Add struct field tags to control how values are loaded:

• env: the env variable name. Use env:"-" to skip a field.
• envDefault: fallback value if the variable is not set.
• envRequired:"true": marks the field as required, returns error when not set, and no default provided.
• envPrefix: for struct-typed fields; prepends a prefix (with underscore) for all nested fields under that struct.

Precedence per field:

1. Value from lookupEnv(name)
2. envDefault (if present)
3. Error if envRequired:"true"

Dynamic Environment Variables

For environment variables that can't be expressed via struct tags, like numbered sequences (USER_1, PASS_1, USER_2, PASS_2) – implement the EnvCollector interface:

package main

import (
	"github.com/struct0x/envconfig"
)

type Config struct {
	Credentials Credentials
}

type Credentials []Credential

type Credential struct {
	User string `env:"USER"`
	Pass string `env:"PASS"`
}

func (c *Credentials) CollectEnv(env envconfig.EnvGetter) error {
	// Read IDs from CREDS=0,1,2 
	var ids []string
	if err := env.ReadValue("CREDS", &ids); err != nil {
		return err
	}

	for _, id := range ids {
		var cred Credential
		// Reads CREDS_0_USER, CREDS_0_PASS, etc.                                                                                                                                                                                                                                                                                                                                                                              
		if err := env.ReadIntoStruct("CREDS_"+id, &cred); err != nil {
			return err
		}
		*c = append(*c, cred)
	}
	return nil
}

Tags are ignored when implementing EnvCollector. The EnvGetter provides three methods:

• Lookup for raw access,
• ReadValue for parsing single values, and
• ReadIntoStruct for populating nested structs with full tag support.

Examples

Basic tags:

package main

type DB struct {
	Host string `env:"DB_HOST" envDefault:"localhost"`
	Port int    `env:"DB_PORT" envRequired:"true"`
}

Nested with prefix:

package main

type SubConfig struct {
	Enabled bool   `env:"ENABLED"`
	Mode    string `env:"MODE" envDefault:"safe"`
}

type Root struct {
	Name string     `env:"NAME"`
	Sub  *SubConfig `envPrefix:"SUB"` // Reads SUB_ENABLED, SUB_MODE
}

Skipping a field:

package main

type T struct {
	Ignored string `env:"-"`
}

Supported types

• string, bool
• []byte - (read as []byte("bytes"), not []byte{'b','y','t','e','s'})
• Integers: int, int8, int16, int32, int64
• Unsigned integers: uint, uint8, uint16, uint32, uint64
• Floats: float32, float64
• time.Duration via time.ParseDuration
• Arrays and slices (comma-separated values): "a,b,c"
• Maps (comma-separated key=value pairs): "k1=v1,k2=v2"
• Pointers to supported types (allocated only when a value is set; nil otherwise)
• Custom types implementing in the following priority:
  • json.Unmarshaler > BinaryUnmarshaler > TextUnmarshaler

If a value cannot be parsed into the target type, Read returns a descriptive error.

Custom lookup (For Secret Managers, Vaults, etc.)

By default, Read uses os.LookupEnv, for more advanced use cases like reading values from secret managers like AWS Secret Manager, HashiCorp Vault you can provide a custom lookup function:

package main

import (
  "context"
  "os"
  "log/slog"

  "github.com/struct0x/envconfig"
)

type SecretResolver struct {
  startingCtx context.Context
  sm          SecretManager
}

func (s *SecretResolver) Lookup(key string) (string, bool) {
  val, ok := os.LookupEnv(key)
  if s.isSecret(val) {
    val, err := s.sm.ResolveSecret(s.startingCtx, val)
    if err != nil {
      slog.Error("missing value", "err", err)
      return "", false
    }
    return val, true
  }

  // fallback to standard lookup
  return val, ok
}

type C struct {
  N int `env:"N"`
}

func main() {
  sm := &SecretResolver{ /*...*/ }
	
  var c C
  _ = envconfig.Read(&c, sm.Lookup)
}

Error handling is your responsibility, use envRequired to ensure values are present regardless of lookup failures.

Additional lookup functions

IgnoreEmptyEnvLookup treats empty env vars as unset.

Error handling

Read returns an error when:

• env tag is empty
• Struct with env tag but no unmarshal interface
• Exported values without env tag
• EnvCollector with value (non-pointer) receiver
• A required field is missing and no default is provided
• holder is nil or not a pointer to a struct
• Struct fields specify both env and envPrefix
• envPrefix is empty when present
• Parsing/conversion failures (returned errors includes the env key)
• Unsupported leaf types (that do not implement a supported unmarshal interface)

Errors include the env variable name and context to aid debugging.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.