A simple, zero-dependencies library to parse environment variables into structs.

Installation

go get github.com/caarlos0/env/v11

Getting started

type config struct {
  Home string `env:"HOME"`
}

// parse
var cfg config
err := env.Parse(&cfg)

// parse with generics
cfg, err := env.ParseAs[config]()

You can see the full documentation and list of examples at pkg.go.dev.

---

Used and supported by

Encore – the platform for building Go-based cloud backends.

Usage

Caveats

Caution

Unexported fields will be ignored by env. This is by design and will not change.

Caution

An environment variable that is set but empty will fall back to the envDefault value, if any. Neither required nor notEmpty guard against this: required is satisfied by the default, while notEmpty only sees the value after the default has been applied.

Functions

• Parse: parse the current environment into a type
• ParseAs: parse the current environment into a type using generics
• ParseWithOptions: parse the current environment into a type with custom options
• ParseAsWithOptions: parse the current environment into a type with custom options and using generics
• Must: can be used to wrap Parse.* calls to panic on error
• GetFieldParams: get the env parsed options for a type
• GetFieldParamsWithOptions: get the env parsed options for a type with custom options

Supported types

Out of the box all built-in types are supported, plus a few others that are commonly used.

Complete list:

• bool
• float32
• float64
• int16
• int32
• int64
• int8
• int
• string
• uint16
• uint32
• uint64
• uint8
• uint
• time.Duration
• time.Location
• encoding.TextUnmarshaler
• url.URL

Pointers, slices and slices of pointers, and maps of those types are also supported.

You may also add custom parsers for your types.

Tags

The following tags are provided:

• env: sets the environment variable name and optionally takes the tag options described below
• envDefault: sets the default value for the field (also used when the environment variable is set but empty)
• envPrefix: can be used in a field that is a complex type to set a prefix to all environment variables used in it
• envSeparator: sets the character to be used to separate items in slices and maps (default: ,)
• envKeyValSeparator: sets the character to be used to separate keys and their values in maps (default: :)

env tag options

Here are all the options available for the env tag:

• ,expand: expands environment variables, e.g. FOO_${BAR}
• ,file: instructs that the content of the variable is a path to a file that should be read
• ,init: initialize nil pointers
• ,notEmpty: make the field errors if the environment variable is empty
• ,required: make the field errors if the environment variable is not set
• ,unset: unset the environment variable after use

Parse Options

There are a few options available in the functions that end with WithOptions:

• Environment: keys and values to be used instead of os.Environ()
• TagName: specifies another tag name to use rather than the default env
• PrefixTagName: specifies another prefix tag name to use rather than the default envPrefix
• DefaultValueTagName: specifies another default tag name to use rather than the default envDefault
• RequiredIfNoDef: set all env fields as required if they do not declare envDefault
• OnSet: allows to hook into the env parsing and do something when a value is set
• Prefix: prefix to be used in all environment variables
• UseFieldNameByDefault: defines whether or not env should use the field name by default if the env key is missing
• FuncMap: custom parse functions for custom types

Documentation and examples

Examples are live in pkg.go.dev, and also in the example test file.

Current state

env is considered feature-complete.

I do not intent to add any new features unless they really make sense, and are requested by many people.

Eventual bug fixes will keep being merged.

Badges

Related projects

• envdoc - generate documentation for environment variables from env tags