caarlos0/env

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.

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
• 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