A simple, zero-dependencies library to parse environment variables into structs.
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.
Encore – the platform for building Go-based cloud backends.
Caution
Unexported fields will be ignored by env
.
This is by design and will not change.
Parse
: parse the current environment into a typeParseAs
: parse the current environment into a type using genericsParseWithOptions
: parse the current environment into a type with custom optionsParseAsithOptions
: parse the current environment into a type with custom options and using genericsMust
: can be used to wrapParse.*
calls to panic on errorGetFieldParams
: get theenv
parsed options for a typeGetFieldParamsWithOptions
: get theenv
parsed options for a type with custom options
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.
The following tags are provided:
env
: sets the environment variable name and optionally takes the tag options described belowenvDefault
: sets the default value for the fieldenvPrefix
: can be used in a field that is a complex type to set a prefix to all environment variables used in itenvSeparator
: 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::
)
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
There are a few options available in the functions that end with WithOptions
:
Environment
: keys and values to be used instead ofos.Environ()
TagName
: specifies another tag name to use rather than the defaultenv
RequiredIfNoDef
: set allenv
fields as required if they do not declareenvDefault
OnSet
: allows to hook into theenv
parsing and do something when a value is setPrefix
: prefix to be used in all environment variablesUseFieldNameByDefault
: defines whether or notenv
should use the field name by default if theenv
key is missingFuncMap
: custom parse functions for custom types
Examples are live in pkg.go.dev, and also in the example test file.
- envdoc - generate documentation for environment variables from
env
tags