GoForj
Support this libraryStar on GitHub

goforj/env logo

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

Go ReferenceLicense: MITGo TestGo versionLatest tagGo Report Card

Features ​

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
  • Safe fallbacks - never panic, never accidentally empty
  • 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
  • Predictable behavior - no magic, no global state surprises
  • Composable building block - ideal for config structs and startup wiring

Why env? ​

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.

Installation ​

bash
go get github.com/goforj/env/v2

Quickstart ​

go
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
}

Scoped prefixes ​

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

go
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
	// ]
}

Full kitchen-sink example ​

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.

Environment loading ​

Load loads env files in this order:

  • .env
  • .env.local, .env.staging, or .env.production, based on APP_ENV (local by default)
  • .env.testing when running under tests
  • .env.host when running on the host or DinD

Later files override earlier ones. Repeated calls are no-ops.

Container detection ​

CheckTrue whenNotes
IsDocker/.dockerenv or Docker cgroup markersGeneric Docker container
IsDockerInDocker/.dockerenv and docker.sockInner DinD container
IsDockerHostdocker.sock present, no container cgroupsHost or DinD outer acting as host
IsContainerAny common container signals (Docker, containerd, kube env/cgroup)General container detection
IsKubernetesKUBERNETES_SERVICE_HOST or kubepods cgroupInside a Kubernetes pod

Runnable examples ​

Every function has a corresponding runnable example under ./examples.

These examples are generated directly from the documentation blocks of each function, ensuring the docs and code never drift. These are the same examples you see here in the README and GoDoc.

An automated test executes every example to verify it builds and runs successfully.

This guarantees all examples are valid, up-to-date, and remain functional as the API evolves.

Environment file loading ​

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.

Philosophy ​

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

No magic. No globals. No surprises.

API Index ​

GroupFunctions
Application environmentGetAppEnv IsAppEnv IsAppEnvLocal IsAppEnvLocalOrStaging IsAppEnvProduction IsAppEnvStaging IsAppEnvTesting IsAppEnvTestingOrLocal SetAppEnv SetAppEnvLocal SetAppEnvProduction SetAppEnvStaging SetAppEnvTesting
Container detectionIsContainer IsDocker IsDockerHost IsDockerInDocker IsHostEnvironment IsKubernetes
DebuggingDump
Environment loadingIsEnvLoaded Load LoadEnvFileIfExists Reload
OtherKey
RuntimeArch IsBSD IsContainerOS IsLinux IsMac IsUnix IsWindows OS
Typed gettersChild ChildNames Get GetBool GetDuration GetEnum GetFloat GetInt GetInt64 GetMap GetMapInt GetSlice GetUint GetUint64 MustGet MustGetBool MustGetInt WithPrefix

Application environment ​

GetAppEnv ​

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

Example: simple retrieval

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

IsAppEnv ​

IsAppEnv checks if APP_ENV matches any of the provided environments.

Example: match any allowed environment

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

Example: unmatched environment

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

IsAppEnvLocal ​

IsAppEnvLocal checks if APP_ENV is "local".

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

IsAppEnvLocalOrStaging ​

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

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

IsAppEnvProduction ​

IsAppEnvProduction checks if APP_ENV is "production".

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

IsAppEnvStaging ​

IsAppEnvStaging checks if APP_ENV is "staging".

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

IsAppEnvTesting ​

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

Example: APP_ENV explicitly testing

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

Example: no test markers

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

IsAppEnvTestingOrLocal ​

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

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

SetAppEnv ​

SetAppEnv sets APP_ENV to a supported value.

Example: set a supported environment

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

SetAppEnvLocal ​

SetAppEnvLocal sets APP_ENV to "local".

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

SetAppEnvProduction ​

SetAppEnvProduction sets APP_ENV to "production".

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

SetAppEnvStaging ​

SetAppEnvStaging sets APP_ENV to "staging".

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

SetAppEnvTesting ​

SetAppEnvTesting sets APP_ENV to "testing".

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

Container detection ​

IsContainer ​

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

Example: host vs container

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

IsDocker ​

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

Example: typical host

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

IsDockerHost ​

IsDockerHost reports whether this container behaves like a Docker host.

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

IsDockerInDocker ​

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

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

IsHostEnvironment ​

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

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

IsKubernetes ​

IsKubernetes reports whether the process is running inside Kubernetes.

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

Debugging ​

Dump ​

Dump is a convenience function that calls godump.Dump.

Example: integers

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

Example: multiple values

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

Environment loading ​

IsEnvLoaded ​

IsEnvLoaded reports whether Load or LoadEnvFileIfExists was executed in this process.

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

Load ​

Load loads .env with optional layering for .env.local/.env.staging/.env.production, plus .env.testing/.env.host when present. It only applies once per process; subsequent calls return without reloading because the result is cached. Use Reload to re-read env files after the first load.

Example: test-specific env file

go
tmp, _ := os.MkdirTemp("", "envdoc")
_ = 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"

Example: default .env on a host

go
_ = os.WriteFile(".env", []byte("SERVICE=api\nENV_DEBUG=3"), 0o644)
_ = env.Load()
env.Dump(os.Getenv("SERVICE"))
// #string "api"

LoadEnvFileIfExists ​

LoadEnvFileIfExists is a compatibility alias for Load.

go
_ = env.LoadEnvFileIfExists()

Reload ​

Reload re-applies the same layered env loading as Load, even if Load already ran earlier in the same process.

Example: refresh changed env files

go
_ = os.WriteFile(".env", []byte("SERVICE=api"), 0o644)
_ = env.Load()
_ = os.WriteFile(".env", []byte("SERVICE=worker"), 0o644)
_ = env.Reload()
env.Dump(os.Getenv("SERVICE"))
// #string "worker"

Other ​

Key ​

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

Runtime ​

Arch ​

Arch returns the CPU architecture the binary is running on.

Example: print GOARCH

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

IsBSD ​

IsBSD reports whether the runtime OS is any BSD variant.

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

IsContainerOS ​

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

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

IsLinux ​

IsLinux reports whether the runtime OS is Linux.

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

IsMac ​

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

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

IsUnix ​

IsUnix reports whether the OS is Unix-like.

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

IsWindows ​

IsWindows reports whether the runtime OS is Windows.

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

OS ​

OS returns the current operating system identifier.

Example: inspect GOOS

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

Typed getters ​

Child ​

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

Example: named child scope

go
_ = 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 ​

ChildNames discovers named child scopes under the current prefix.

Example: discover child names

go
_ = 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 ​

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

Example: fallback when unset

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

Example: prefer existing value

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

GetBool ​

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

Example: numeric truthy

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

Example: fallback string

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

GetDuration ​

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

Example: override request timeout

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

Example: fallback when unset

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

GetEnum ​

GetEnum ensures the environment variable's value is in the allowed list.

Example: accept only staged environments

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

Example: fallback when unset

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

GetFloat ​

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

Example: override threshold

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

Example: fallback with decimal string

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

GetInt ​

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

Example: fallback used

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

Example: env overrides fallback

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

GetInt64 ​

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

Example: parse large numbers safely

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

Example: fallback when unset

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

GetMap ​

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

Example: parse throttling config

go
_ = 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

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

GetMapInt ​

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

go
_ = 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

go
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 ​

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

Example: trimmed addresses

go
_ = 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

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

GetUint ​

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

Example: defaults to fallback when missing

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

Example: uses provided unsigned value

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

GetUint64 ​

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

Example: high range values

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

Example: fallback when unset

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

MustGet ​

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

Example: required secret

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

Example: panic on missing value

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

MustGetBool ​

MustGetBool panics if missing or invalid.

Example: gate features explicitly

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

Example: panic on invalid value

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

MustGetInt ​

MustGetInt panics if the value is missing or not an int.

Example: ensure numeric port

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

Example: panic on bad value

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

WithPrefix ​

WithPrefix returns a scope rooted at prefix after minimal normalization.

Example: root scope access

go
_ = 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"

License ​

MIT