Typed environment variables for Go - safe defaults, app env helpers, and zero-ceremony configuration.

env provides strongly-typed access to environment variables with predictable fallbacks. Eliminate string parsing, centralize app environment checks, and keep configuration boring. Designed to feel native to Go - and invisible when things are working.

• Strongly typed getters - int, bool, float, duration, slices, maps
• Explicit fallback and required-value APIs - fallback getters stay permissive; MustGet* panics on missing or invalid required values
• Application environment helpers - local, staging, production
• Minimal dependencies - Pure Go, lightweight, minimal surface area
• Framework-agnostic - works with any Go app
• Enum validation - constrain values with allowed sets
• Transactional env loading - discovery, parsing, and process updates succeed together or leave the prior environment intact
• Composable building block - ideal for config structs and startup wiring

Accessing environment variables in Go often leads to:

• Repeated parsing logic
• Unsafe string conversions
• Inconsistent defaults
• Scattered app environment checks

env solves this by providing typed accessors with fallbacks, so configuration stays boring and predictable.

go get github.com/goforj/env/v2

package main

import (
	"log"
	"time"

	"github.com/goforj/env/v2"
)

func init() {
	if err := env.Load(); err != nil {
		log.Fatalf("load env: %v", err)
	}
}

func main() {
	addr := env.Get("ADDR", "127.0.0.1:8080")
	debug := env.GetBool("DEBUG", "false")
	timeout := env.GetDuration("HTTP_TIMEOUT", "5s")

	env.Dump(addr, debug, timeout)
	// #string "127.0.0.1:8080"
	// #bool false
	// #time.Duration 5s

	env.Dump("container?", env.IsContainer())
	// #string "container?"
	// #bool false
}

Use Scope when a group of related settings share a common prefix and may also expose named child configs.

package main

import (
	"os"

	"github.com/goforj/env/v2"
)

func main() {
	_ = os.Setenv("STORAGE_DRIVER", "local")
	_ = os.Setenv("STORAGE_ROOT", "storage/app/private")
	_ = os.Setenv("STORAGE_PUBLIC_DRIVER", "local")
	_ = os.Setenv("STORAGE_PUBLIC_ROOT", "storage/app/public")
	_ = os.Setenv("STORAGE_AVATARS_DRIVER", "s3")
	_ = os.Setenv("STORAGE_AVATARS_BUCKET", "my-bucket")
	_ = os.Setenv("STORAGE_AVATARS_REGION", "us-east-1")

	storage := env.WithPrefix("STORAGE")

	// Root/default config reads STORAGE_* keys.
	driver := storage.Get("DRIVER", "local")
	root := storage.Get("ROOT", "storage/app/private")

	public := storage.Child("PUBLIC")

	// Child scopes compose STORAGE_<NAME>_* keys.
	publicDriver := public.Get("DRIVER", "local")
	publicRoot := public.Get("ROOT", "storage/app/public")

	// ChildNames discovers named children while ignoring root keys.
	names := storage.ChildNames([]string{
		"DRIVER",
		"ROOT",
		"BUCKET",
		"REGION",
	})

	env.Dump(driver, root, publicDriver, publicRoot, names)
	// #string "local"
	// #string "storage/app/private"
	// #string "local"
	// #string "storage/app/public"
	// #[]string [
	//  0 => "AVATARS" #string
	//  1 => "PUBLIC" #string
	// ]
}

See examples/kitchensink/main.go for a runnable program that exercises almost every helper (env loading, typed getters, must-getters, runtime + container detection, and the env.Dump wrapper) with deterministic godump output.

Load searches for and applies env files in this order:

• .env
• .env.local, .env.staging, or .env.production, based on APP_ENV (local by default)
• .env.host when running on the host or DinD
• .env.testing when APP_ENV=testing or the process has Go test markers

Each filename is discovered independently, starting in the working directory and checking at most nine ancestors. The nearest regular file wins; regular-file symlinks are followed. Later files override earlier files, while existing process variables override every file. An explicitly empty process variable still counts as existing.

Discovery and parsing finish before any process mutation. Load returns filesystem and parse errors instead of panicking, rolls back a failed environment update, and becomes a no-op after its first success. A failed call leaves IsEnvLoaded false and preserves the prior process environment.

Load, Reload, and IsEnvLoaded synchronize with one another. Direct os.Setenv or os.Unsetenv calls are outside that lock, so applications that mutate the same keys concurrently must coordinate those writes themselves.

Reload always rediscovers the selected files. An unchanged value previously supplied by a file remains file-owned and refreshes from disk. If application code changes its visible value, the process takes ownership and Reload leaves it alone. An unset key is missing again and may be supplied by a file on the next reload; set it to an explicitly empty value when that empty process value must remain authoritative. Any other process value present when Reload discovers a new file key also remains authoritative. If an unchanged file-owned key disappears from every file, its exact pre-load process state is restored, including the difference between unset and explicitly empty. Unrelated variables are untouched. A failed reload preserves the last successful configuration.

An existing process APP_ENV selects the application layer and cannot be replaced by a file. An explicitly empty process APP_ENV selects local files while remaining empty. When the process does not provide APP_ENV, .env may select the application layer; if neither source provides it, the loader defaults it to local. A file-owned APP_ENV is refreshed before layer selection on reload.

Load and Reload now follow the conventional dotenv precedence rule: existing process variables win and dotenv files supply missing values. Applications that intentionally relied on a file replacing an exported process variable should unset that variable before calling Load.

The public v2 call shapes are unchanged. The quality pass makes previously implicit failure and reload behavior explicit:

• Load and Reload return dotenv, filesystem, and environment-application errors rather than panicking.
• Reload restores removed file keys to their pre-first-load ambient values instead of blindly unsetting them.
• MustGetInt and MustGetBool now honor their documented contract and panic for missing or invalid values.
• GetUint parses at the platform's native uint width, and GetMap trims keys and values around =.
• LoadEnvFileIfExists remains a compatibility alias for Load.

Dump intentionally prints the raw values passed to it and performs no redaction. Never pass credentials, tokens, private keys, or other secrets. Loader diagnostics (ENV_DEBUG=3) print only selected file paths and APP_ENV, never dotenv keys or values.

The process environment is the highest-priority configuration source. Sanitize values inherited from an untrusted launcher before calling Load. Child processes normally inherit the resolved environment; construct exec.Cmd.Env explicitly when crossing a trust boundary or when a child must load an independent configuration.

Documented examples are generated directly from function documentation into ./examples, so the README, GoDoc, and example programs share one source. CI regenerates them to detect drift and builds every generated program without build tags. Examples that intentionally demonstrate panic behavior are compiled rather than executed.

This package uses github.com/joho/godotenv for .env file loading.

It is intentionally composed into the runtime detection and APP_ENV model rather than reimplemented.

env is part of the GoForj toolchain - a collection of focused, composable packages designed to make building Go applications satisfying.

Small APIs. Explicit process mutation. Predictable failure modes.

GetAppEnv returns the current APP_ENV (empty string if unset).

Example: simple retrieval

_ = os.Setenv("APP_ENV", "staging")
env.Dump(env.GetAppEnv())
// #string "staging"

IsAppEnv checks if APP_ENV matches any of the provided environments.

Example: match any allowed environment

_ = os.Setenv("APP_ENV", "staging")
env.Dump(env.IsAppEnv(env.Production, env.Staging))
// #bool true

Example: unmatched environment

_ = os.Setenv("APP_ENV", "local")
env.Dump(env.IsAppEnv(env.Production, env.Staging))
// #bool false

IsAppEnvLocal checks if APP_ENV is "local".

_ = os.Setenv("APP_ENV", env.Local)
env.Dump(env.IsAppEnvLocal())
// #bool true

IsAppEnvLocalOrStaging checks if APP_ENV is either "local" or "staging".

_ = os.Setenv("APP_ENV", env.Local)
env.Dump(env.IsAppEnvLocalOrStaging())
// #bool true

IsAppEnvProduction checks if APP_ENV is "production".

_ = os.Setenv("APP_ENV", env.Production)
env.Dump(env.IsAppEnvProduction())
// #bool true

IsAppEnvStaging checks if APP_ENV is "staging".

_ = os.Setenv("APP_ENV", env.Staging)
env.Dump(env.IsAppEnvStaging())
// #bool true

IsAppEnvTesting reports whether APP_ENV is "testing" or the process looks like go test.

Example: APP_ENV explicitly testing

_ = os.Setenv("APP_ENV", env.Testing)
env.Dump(env.IsAppEnvTesting())
// #bool true

Example: no test markers

_ = os.Unsetenv("APP_ENV")
env.Dump(env.IsAppEnvTesting())
// #bool false (outside of test binaries)

IsAppEnvTestingOrLocal checks if APP_ENV is "testing" or "local".

_ = os.Setenv("APP_ENV", env.Testing)
env.Dump(env.IsAppEnvTestingOrLocal())
// #bool true

SetAppEnv sets APP_ENV to a supported value.

Example: set a supported environment

_ = env.SetAppEnv(env.Staging)
env.Dump(env.GetAppEnv())
// #string "staging"

SetAppEnvLocal sets APP_ENV to "local".

_ = env.SetAppEnvLocal()
env.Dump(env.GetAppEnv())
// #string "local"

SetAppEnvProduction sets APP_ENV to "production".

_ = env.SetAppEnvProduction()
env.Dump(env.GetAppEnv())
// #string "production"

SetAppEnvStaging sets APP_ENV to "staging".

_ = env.SetAppEnvStaging()
env.Dump(env.GetAppEnv())
// #string "staging"

SetAppEnvTesting sets APP_ENV to "testing".

_ = env.SetAppEnvTesting()
env.Dump(env.GetAppEnv())
// #string "testing"

IsContainer detects common container runtimes (Docker, containerd, Kubernetes, Podman).

Example: host vs container

env.Dump(env.IsContainer())
// #bool true  (inside most containers)
// #bool false (on bare-metal/VM hosts)

IsDocker reports whether the current process is running in a Docker container.

Example: typical host

env.Dump(env.IsDocker())
// #bool false (unless inside Docker)

IsDockerHost reports whether this container behaves like a Docker host.

env.Dump(env.IsDockerHost())
// #bool true  (when acting as Docker host)
// #bool false (for normal containers/hosts)

IsDockerInDocker reports whether we are inside a Docker-in-Docker environment.

env.Dump(env.IsDockerInDocker())
// #bool true  (inside DinD containers)
// #bool false (on hosts or non-DinD containers)

IsHostEnvironment reports whether the process is running outside any container or orchestrated runtime.

env.Dump(env.IsHostEnvironment())
// #bool true  (on bare-metal/VM hosts)
// #bool false (inside containers)

IsKubernetes reports whether the process is running inside Kubernetes.

env.Dump(env.IsKubernetes())
// #bool true  (inside Kubernetes pods)
// #bool false (elsewhere)

Dump writes complete representations of its arguments to standard output.

Example: integers

nums := []int{1, 2, 3}
env.Dump(nums)
// #[]int [
//   0 => 1 #int
//   1 => 2 #int
//   2 => 3 #int
// ]

Example: multiple values

env.Dump("status", map[string]int{"ok": 1, "fail": 0})
// #string "status"
// #map[string]int [
//   "fail" => 0 #int
//   "ok"   => 1 #int
// ]

IsEnvLoaded reports whether a Load or Reload completed successfully in this process.

env.Dump(env.IsEnvLoaded())
// #bool true  (after Load)
// #bool false (otherwise)

Load loads the nearest env files with deterministic layering.

Load applies once per process. Existing process values override files, and later files override earlier files for keys absent from the process environment. Discovery and parsing complete before the process environment changes; errors leave both the environment and loader state unchanged. Use Reload to re-read files.

Example: test-specific env file

tmp, _ := os.MkdirTemp("", "envdoc")
defer os.RemoveAll(tmp)
originalDirectory, _ := os.Getwd()
defer os.Chdir(originalDirectory)
_ = os.WriteFile(filepath.Join(tmp, ".env.testing"), []byte("PORT=9090\nENV_DEBUG=0"), 0o644)
_ = os.Chdir(tmp)
_ = os.Setenv("APP_ENV", env.Testing)

_ = env.Load()
env.Dump(os.Getenv("PORT"))
// #string "9090"

LoadEnvFileIfExists is a compatibility alias for Load.

_ = env.LoadEnvFileIfExists()

Reload re-discovers and transactionally reapplies env files even after Load has run.

Keys loaded from files remain file-owned until application code changes their visible value. Reload refreshes unchanged file-owned keys while preserving process overrides. An unset key is missing and may be supplied by a file again. When a key disappears from all files, Reload restores the process value (including unset versus empty) that existed before the first successful Load. Unrelated process variables are never changed.

Example: refresh changed env files

tmp, _ := os.MkdirTemp("", "envdoc")
defer os.RemoveAll(tmp)
originalDirectory, _ := os.Getwd()
defer os.Chdir(originalDirectory)
_ = os.Chdir(tmp)
_ = os.WriteFile(filepath.Join(tmp, ".env"), []byte("SERVICE=api"), 0o644)
_ = env.Load()
_ = os.WriteFile(filepath.Join(tmp, ".env"), []byte("SERVICE=worker"), 0o644)
_ = env.Reload()
env.Dump(os.Getenv("SERVICE"))
// #string "worker"

Arch returns the CPU architecture the binary is running on.

Example: print GOARCH

env.Dump(env.Arch())
// #string "amd64"
// #string "arm64"

IsBSD reports whether the runtime OS is any BSD variant.

env.Dump(env.IsBSD())
// #bool true  (on BSD variants)
// #bool false (elsewhere)

IsContainerOS reports whether this OS is typically used as a container base.

env.Dump(env.IsContainerOS())
// #bool true  (on Linux)
// #bool false (on macOS/Windows)

IsLinux reports whether the runtime OS is Linux.

env.Dump(env.IsLinux())
// #bool true  (on Linux)
// #bool false (on other OSes)

IsMac reports whether the runtime OS is macOS (Darwin).

env.Dump(env.IsMac())
// #bool true  (on macOS)
// #bool false (elsewhere)

IsUnix reports whether the OS is Unix-like.

env.Dump(env.IsUnix())
// #bool true  (on Unix-like OSes)
// #bool false (e.g., on Windows or Plan 9)

IsWindows reports whether the runtime OS is Windows.

env.Dump(env.IsWindows())
// #bool true  (on Windows)
// #bool false (elsewhere)

OS returns the current operating system identifier.

Example: inspect GOOS

env.Dump(env.OS())
// #string "linux"   (on Linux)
// #string "darwin"  (on macOS)
// #string "windows" (on Windows)

Get returns the environment variable for key or fallback when empty.

Example: fallback when unset

os.Unsetenv("DB_HOST")
host := env.Get("DB_HOST", "localhost")
env.Dump(host)
// #string "localhost"

Example: prefer existing value

_ = os.Setenv("DB_HOST", "db.internal")
host = env.Get("DB_HOST", "localhost")
env.Dump(host)
// #string "db.internal"

GetBool parses a boolean from an environment variable or fallback string.

Example: numeric truthy

_ = os.Setenv("DEBUG", "1")
debug := env.GetBool("DEBUG", "false")
env.Dump(debug)
// #bool true

Example: fallback string

os.Unsetenv("DEBUG")
debug = env.GetBool("DEBUG", "false")
env.Dump(debug)
// #bool false

GetDuration parses a Go duration string (e.g. "5s", "10m", "1h").

Example: override request timeout

_ = os.Setenv("HTTP_TIMEOUT", "30s")
timeout := env.GetDuration("HTTP_TIMEOUT", "5s")
env.Dump(timeout)
// #time.Duration 30s

Example: fallback when unset

os.Unsetenv("HTTP_TIMEOUT")
timeout = env.GetDuration("HTTP_TIMEOUT", "5s")
env.Dump(timeout)
// #time.Duration 5s

GetEnum returns the environment value when allowed and fallback otherwise.

Example: accept only staged environments

_ = os.Setenv("APP_ENV", "production")
appEnv := env.GetEnum("APP_ENV", "local", []string{"local", "staging", "production"})
env.Dump(appEnv)
// #string "production"

Example: fallback when unset

os.Unsetenv("APP_ENV")
appEnv = env.GetEnum("APP_ENV", "local", []string{"local", "staging", "production"})
env.Dump(appEnv)
// #string "local"

GetFloat parses a float64 from an environment variable or fallback string.

Example: override threshold

_ = os.Setenv("THRESHOLD", "0.82")
threshold := env.GetFloat("THRESHOLD", "0.75")
env.Dump(threshold)
// #float64 0.82

Example: fallback with decimal string

os.Unsetenv("THRESHOLD")
threshold = env.GetFloat("THRESHOLD", "0.75")
env.Dump(threshold)
// #float64 0.75

GetInt parses an int from an environment variable or fallback string.

Example: fallback used

os.Unsetenv("PORT")
port := env.GetInt("PORT", "3000")
env.Dump(port)
// #int 3000

Example: env overrides fallback

_ = os.Setenv("PORT", "8080")
port = env.GetInt("PORT", "3000")
env.Dump(port)
// #int 8080

GetInt64 parses an int64 from an environment variable or fallback string.

Example: parse large numbers safely

_ = os.Setenv("MAX_SIZE", "1048576")
size := env.GetInt64("MAX_SIZE", "512")
env.Dump(size)
// #int64 1048576

Example: fallback when unset

os.Unsetenv("MAX_SIZE")
size = env.GetInt64("MAX_SIZE", "512")
env.Dump(size)
// #int64 512

GetMap parses trimmed key=value pairs separated by commas into a map.

Example: parse throttling config

_ = os.Setenv("LIMITS", "read=10, write=5, burst=20")
limits := env.GetMap("LIMITS", "")
env.Dump(limits)
// #map[string]string [
//  "burst" => "20" #string
//  "read"  => "10" #string
//  "write" => "5" #string
// ]

Example: returns empty map when unset or blank

os.Unsetenv("LIMITS")
limits = env.GetMap("LIMITS", "")
env.Dump(limits)
// #map[string]string []

GetMapInt parses key=int pairs separated by commas into a map. Invalid, missing, or non-positive values fall back to defaultValue.

Example: parse worker queue weights

_ = os.Setenv("QUEUE_WEIGHTS", "critical=6, default=3, low=1")
weights := env.GetMapInt("QUEUE_WEIGHTS", "", 1)
env.Dump(weights)
// #map[string]int [
//  "critical" => 6 #int
//  "default"  => 3 #int
//  "low"      => 1 #int
// ]

Example: invalid values use defaultValue

os.Unsetenv("QUEUE_WEIGHTS")
weights = env.GetMapInt("QUEUE_WEIGHTS", "critical=,default=0,low=nope,misc", 2)
env.Dump(weights)
// #map[string]int [
//  "critical" => 2 #int
//  "default"  => 2 #int
//  "low"      => 2 #int
//  "misc"     => 2 #int
// ]

GetSlice splits a comma-separated string into a []string with trimming.

Example: trimmed addresses

_ = os.Setenv("PEERS", "10.0.0.1, 10.0.0.2")
peers := env.GetSlice("PEERS", "")
env.Dump(peers)
// #[]string [
//  0 => "10.0.0.1" #string
//  1 => "10.0.0.2" #string
// ]

Example: empty becomes empty slice

os.Unsetenv("PEERS")
peers = env.GetSlice("PEERS", "")
env.Dump(peers)
// #[]string []

GetUint parses a uint from an environment variable or fallback string.

Example: defaults to fallback when missing

os.Unsetenv("WORKERS")
workers := env.GetUint("WORKERS", "4")
env.Dump(workers)
// #uint 4

Example: uses provided unsigned value

_ = os.Setenv("WORKERS", "16")
workers = env.GetUint("WORKERS", "4")
env.Dump(workers)
// #uint 16

GetUint64 parses a uint64 from an environment variable or fallback string.

Example: high range values

_ = os.Setenv("MAX_ITEMS", "5000")
maxItems := env.GetUint64("MAX_ITEMS", "100")
env.Dump(maxItems)
// #uint64 5000

Example: fallback when unset

os.Unsetenv("MAX_ITEMS")
maxItems = env.GetUint64("MAX_ITEMS", "100")
env.Dump(maxItems)
// #uint64 100

MustGet returns the value of key or panics if missing/empty.

Example: required secret

_ = os.Setenv("API_SECRET", "s3cr3t")
secret := env.MustGet("API_SECRET")
env.Dump(secret)
// #string "s3cr3t"

Example: panic on missing value

os.Unsetenv("API_SECRET")
secret = env.MustGet("API_SECRET") // panics: env variable missing: API_SECRET

MustGetBool returns a required bool or panics when the value is missing or invalid.

Example: gate features explicitly

_ = os.Setenv("FEATURE_ENABLED", "true")
enabled := env.MustGetBool("FEATURE_ENABLED")
env.Dump(enabled)
// #bool true

Example: panic on invalid value

_ = os.Setenv("FEATURE_ENABLED", "maybe")
_ = env.MustGetBool("FEATURE_ENABLED") // panics when parsing

MustGetInt returns a required int or panics when the value is missing or invalid.

Example: ensure numeric port

_ = os.Setenv("PORT", "8080")
port := env.MustGetInt("PORT")
env.Dump(port)
// #int 8080

Example: panic on bad value

_ = os.Setenv("PORT", "not-a-number")
_ = env.MustGetInt("PORT") // panics when parsing

Child returns a new scope rooted at the current prefix plus name.

Example: named child scope

_ = os.Setenv("STORAGE_PUBLIC_ROOT", "storage/app/public")

public := env.WithPrefix("STORAGE").Child("PUBLIC")
env.Dump(
	public.Key("ROOT"),
	public.Get("ROOT", "storage/app/public"),
)
// #string "STORAGE_PUBLIC_ROOT"
// #string "storage/app/public"

ChildNames discovers named child scopes under the current prefix.

Example: discover child names

_ = os.Setenv("STORAGE_DRIVER", "local")
_ = os.Setenv("STORAGE_ROOT", "storage/app/private")
_ = os.Setenv("STORAGE_PUBLIC_ROOT", "storage/app/public")
_ = os.Setenv("STORAGE_AVATARS_BUCKET", "my-bucket")
_ = os.Setenv("STORAGE_AVATARS_REGION", "us-east-1")

names := env.WithPrefix("STORAGE").ChildNames([]string{
	"DRIVER",
	"ROOT",
	"BUCKET",
	"REGION",
})
env.Dump(names)
// #[]string [
//  0 => "AVATARS" #string
//  1 => "PUBLIC" #string
// ]

Get returns the string value for key within the scope.

GetBool returns the bool value for key within the scope.

GetDuration returns the duration value for key within the scope.

GetEnum returns the enum value for key within the scope.

GetFloat returns the float64 value for key within the scope.

GetInt returns the int value for key within the scope.

GetInt64 returns the int64 value for key within the scope.

GetMap returns the string map value for key within the scope.

GetMapInt returns the int map value for key within the scope.

GetSlice returns the string slice value for key within the scope.

GetUint returns the uint value for key within the scope.

GetUint64 returns the uint64 value for key within the scope.

Key builds the fully qualified environment key for key within the scope.

WithPrefix returns a scope rooted at prefix after minimal normalization.

Example: root scope access

_ = os.Setenv("STORAGE_DRIVER", "local")
_ = os.Setenv("STORAGE_ROOT", "storage/app/private")

storage := env.WithPrefix(" STORAGE ")
env.Dump(
	storage.Key("DRIVER"),
	storage.Get("DRIVER", "s3"),
	storage.Get("ROOT", "storage/app/private"),
)
// #string "STORAGE_DRIVER"
// #string "local"
// #string "storage/app/private"

MIT