env Documentation

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 Copy Chapter

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

Usage Copy Chapter

Caveats Copy Section

[!CAUTION]

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

Functions Copy Section

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

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 Copy Section

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 Copy Section

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 Copy Section

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 Copy Section

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

Current state Copy Chapter

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 Copy Chapter

Related projects Copy Chapter

• envdoc - generate documentation for environment variables from env tags