How to load a .env with the dotenv library, and what every read accessor returns, including for duplicate keys and commented-out settings.
On this page
- Which call to use
- Before you start
- Step 1 — Read the values in one call
- Step 2 — Open a file you may edit
- Step 3 — Parse a string or a reader
- Step 4 — Query the file
- Step 5 — Check where the file came from
- Try it
- Cost at scale
- Pitfalls
- Related
There are four ways in. Pick by where the content lives and whether you will write it back.
| You have | You want | Call | Missing file |
|---|---|---|---|
| a path | the final values, ${refs} resolved, read-only |
dotenv.Read(path) → map[string]string |
error |
| a path | to inspect, edit and save the file | dotenv.Open(path) → *File |
not an error: an empty File |
| a string | to inspect or edit content already in memory | dotenv.Parse(content) → *File |
n/a |
an io.Reader |
the same, from a pipe, an HTTP body or an open file | dotenv.ParseReader(r) → *File |
n/a |
Read is Open followed by ExpandedMap. The other three give you a *File, whose accessors return raw values: a ${DOMAIN} reference stays as written, so saving the file never flattens it. When you want resolved values from a *File, use GetExpanded or ExpandedMap (see expansion.md).
None of these touch os.Environ. Reading a file and exporting it into the process are separate decisions; the library only does the first.
go get github.com/ubgo/dotenvThe library needs Go 1.22 or later and has no third-party dependencies.
Use Read when a program only consumes configuration. It skips comments, blanks, disabled settings and unrecognised lines, collapses duplicates to the last one, and resolves ${VAR} references against the same file. Unlike Open, a missing file is an error, because Read is for consuming a file that should exist.
// ExampleRead loads a file straight into a map with every ${reference}
// resolved: the one-call path for a program that only consumes configuration
// and never writes the file back.
func ExampleRead() {
// envFile is the name the example writes inside its own temp directory.
const envFile = ".env"
dir, err := os.MkdirTemp("", "dotenv-read")
if err != nil {
fmt.Println(err)
return
}
defer func() {
// Cleanup is best-effort; a failure goes to stderr so the example's
// checked stdout output is unaffected.
if err := os.RemoveAll(dir); err != nil {
fmt.Fprintln(os.Stderr, "cleanup:", err)
}
}()
path := filepath.Join(dir, envFile)
content := "DOMAIN=example.com\nAPI_URL=https://api.${DOMAIN}\n# DEBUG=true\n"
if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
fmt.Println(err)
return
}
m, err := dotenv.Read(path)
if err != nil {
fmt.Println(err)
return
}
// A map has no order; sort the keys so the output is stable.
keys := make([]string, 0, len(m))
for k := range m {
keys = append(keys, k)
}
sort.Strings(keys)
for _, k := range keys {
fmt.Printf("%s=%s\n", k, m[k])
}
// Unlike Open, Read treats a missing file as an error.
_, err = dotenv.Read(filepath.Join(dir, "missing.env"))
fmt.Println("missing file is an error:", err != nil)
// Output:
// API_URL=https://api.example.com
// DOMAIN=example.com
// missing file is an error: true
}Example: ExampleRead.
Use Open when you will inspect structure, edit or save. It records the path, the file's permissions and whether it existed. Values come back raw.
// ExampleOpen opens a file from disk for reading and editing. Values come back
// raw: a ${reference} stays as written, so the file can be saved without
// flattening it.
func ExampleOpen() {
// envFile is the name the example writes inside its own temp directory.
const envFile = ".env"
dir, err := os.MkdirTemp("", "dotenv-open")
if err != nil {
fmt.Println(err)
return
}
defer func() {
// Cleanup is best-effort; a failure goes to stderr so the example's
// checked stdout output is unaffected.
if err := os.RemoveAll(dir); err != nil {
fmt.Fprintln(os.Stderr, "cleanup:", err)
}
}()
path := filepath.Join(dir, envFile)
content := "DOMAIN=example.com\nAPI_URL=https://api.${DOMAIN}\n"
if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
fmt.Println(err)
return
}
f, err := dotenv.Open(path)
if err != nil {
fmt.Println(err)
return
}
v, ok := f.Get("API_URL")
fmt.Println(v, ok)
fmt.Println("existed:", f.Existed())
// Output:
// https://api.${DOMAIN} true
// existed: true
}A missing file is not an error. You get an empty File; Existed reports false, and Save creates the file with mode 0600. That is how a tool bootstraps a fresh .env:
// ExampleOpen_missing shows that opening a file that does not exist is not an
// error: you get an empty File you can fill and Save, which creates it.
func ExampleOpen_missing() {
// envFile is the name the example creates inside its own temp directory.
const envFile = ".env"
dir, err := os.MkdirTemp("", "dotenv-open-missing")
if err != nil {
fmt.Println(err)
return
}
defer func() {
// Cleanup is best-effort; a failure goes to stderr so the example's
// checked stdout output is unaffected.
if err := os.RemoveAll(dir); err != nil {
fmt.Fprintln(os.Stderr, "cleanup:", err)
}
}()
f, err := dotenv.Open(filepath.Join(dir, envFile))
if err != nil {
fmt.Println(err)
return
}
fmt.Println("existed:", f.Existed(), "keys:", len(f.Keys()))
f.Set("PORT", "8080")
if err := f.Save(); err != nil {
fmt.Println(err)
return
}
data, err := os.ReadFile(filepath.Join(dir, envFile))
if err != nil {
fmt.Println(err)
return
}
fmt.Printf("%q\n", data)
// Output:
// existed: false keys: 0
// "PORT=8080\n"
}Open returns an error for every other failure: a file it may not read, or a path that is a directory. The message names the path and the failed step (dotenv: open <path>: … or dotenv: read <path>: …).
Examples: ExampleOpen, ExampleOpen_missing.
Parse takes a string and never fails: any line it does not understand is kept as an "other" entry rather than rejected (see entries.md). Rendering an untouched File gives back the exact input bytes.
// ExampleParse parses a string with no filesystem involved: an embedded fixture,
// a value from a secret store, or a test input. Rendering it back gives the
// exact bytes it was parsed from.
func ExampleParse() {
const content = "# app\nPORT=8080\nexport NAME='my app'\n"
f := dotenv.Parse(content)
port, _ := f.Get("PORT")
name, _ := f.Get("NAME")
fmt.Println(port)
fmt.Println(name)
fmt.Println("round trip:", f.Render() == content)
// Output:
// 8080
// my app
// round trip: true
}ParseReader takes any io.Reader. Prefer it over io.ReadAll followed by Parse for large input: it copies the content once into a strings.Builder, while io.ReadAll grows its buffer by doubling and the []byte to string conversion copies everything again. Its only error is the reader's own error, wrapped as dotenv: read: ….
// ExampleParseReader parses from any io.Reader: a pipe, an HTTP body, a file
// you already opened. It copies the input once, so it is the cheaper choice
// for large content compared with io.ReadAll followed by Parse.
func ExampleParseReader() {
r := strings.NewReader("PORT=8080\nHOST=localhost\n")
f, err := dotenv.ParseReader(r)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(f.Keys())
// Output:
// [PORT HOST]
}Both accept the same options as Open (for example dotenv.WithEscapes, or plugins). A File from Parse or ParseReader has an empty Path and Existed() == false; set Path before calling Save (see Step 5).
Examples: ExampleParse, ExampleParseReader.
Six accessors read a File. They differ only in how they treat duplicates; all six ignore everything that is not an active pair, which means comments, blanks, unrecognised lines, commented-out settings (# DB_USER=admin) and name-only inherited lines (HOME).
Every example below parses the same input:
# database
DB_HOST=localhost
DB_PORT=5432
# DB_USER=admin
DB_HOST=db.internal
HOMEDB_HOST is set twice, DB_USER is commented out, and HOME is a name with no value. Here is what each accessor returns for it. Every cell is checked by an Example's // Output: block.
| Call | Returns | Duplicates | Disabled DB_USER |
Inherited HOME |
|---|---|---|---|---|
f.Get("DB_HOST") |
"db.internal", true |
last line wins | Get("DB_USER") → "", false |
Get("HOME") → "", false |
f.Has("DB_HOST") |
true |
any active line counts | false |
false |
f.Count("DB_HOST") |
2 |
counts every active line | 0 |
0 |
f.Keys() |
[DB_HOST DB_PORT] |
each key once, first-seen order | left out | left out |
f.Pairs() |
DB_HOST=localhost, DB_PORT=5432, DB_HOST=db.internal |
every line, file order | left out | left out |
f.Map() |
2 keys: DB_HOST → db.internal, DB_PORT → 5432 |
last line wins | left out | left out |
Get returns a value and a found flag. Use the flag: an empty value (KEY=) and a missing key both give "".
// ExampleFile_Get reads one raw value. With a duplicated key the LAST active
// line wins, a commented-out setting is not found, and neither is a name-only
// (inherited) line.
func ExampleFile_Get() {
const content = `# database
DB_HOST=localhost
DB_PORT=5432
# DB_USER=admin
DB_HOST=db.internal
HOME
`
f := dotenv.Parse(content)
for _, key := range []string{"DB_HOST", "DB_PORT", "DB_USER", "HOME", "NOPE"} {
v, ok := f.Get(key)
fmt.Printf("%s: %q %v\n", key, v, ok)
}
// Output:
// DB_HOST: "db.internal" true
// DB_PORT: "5432" true
// DB_USER: "" false
// HOME: "" false
// NOPE: "" false
}Has is Get without the value.
// ExampleFile_Has checks for an ACTIVE pair. A disabled setting and an
// inherited name both answer false, because neither is in effect.
func ExampleFile_Has() {
const content = `# database
DB_HOST=localhost
DB_PORT=5432
# DB_USER=admin
DB_HOST=db.internal
HOME
`
f := dotenv.Parse(content)
fmt.Println("DB_HOST:", f.Has("DB_HOST"))
fmt.Println("DB_USER:", f.Has("DB_USER"))
fmt.Println("HOME:", f.Has("HOME"))
// Output:
// DB_HOST: true
// DB_USER: false
// HOME: false
}Count is how you find duplicates. Only the last line of a duplicated key is in effect; the earlier ones are dead weight a reviewer should hear about.
// ExampleFile_Count reports how many active lines share a key. Anything above
// one is a duplicate: only the last line is in effect, the others are dead
// weight a reviewer should know about.
func ExampleFile_Count() {
const content = `# database
DB_HOST=localhost
DB_PORT=5432
# DB_USER=admin
DB_HOST=db.internal
HOME
`
f := dotenv.Parse(content)
for _, key := range f.Keys() {
if n := f.Count(key); n > 1 {
fmt.Printf("%s is set %d times\n", key, n)
}
}
fmt.Println("DB_USER:", f.Count("DB_USER"))
// Output:
// DB_HOST is set 2 times
// DB_USER: 0
}Keys lists each active key once, in the order it first appears.
// ExampleFile_Keys lists the active keys in file order, each once. Disabled
// settings and inherited names are left out.
func ExampleFile_Keys() {
const content = `# database
DB_HOST=localhost
DB_PORT=5432
# DB_USER=admin
DB_HOST=db.internal
HOME
`
f := dotenv.Parse(content)
fmt.Println(f.Keys())
// Output:
// [DB_HOST DB_PORT]
}Pairs returns every active line as a Pair{Key, Value} in file order, duplicates included: the view a linear read of the file gives.
// ExampleFile_Pairs lists every active pair in file order, duplicates
// included: the view a linear read of the file gives.
func ExampleFile_Pairs() {
const content = `# database
DB_HOST=localhost
DB_PORT=5432
# DB_USER=admin
DB_HOST=db.internal
HOME
`
f := dotenv.Parse(content)
for _, p := range f.Pairs() {
fmt.Printf("%s=%s\n", p.Key, p.Value)
}
// Output:
// DB_HOST=localhost
// DB_PORT=5432
// DB_HOST=db.internal
}Map is the effective view, one value per key with the last line winning, the same answer Get gives. Hand it to anything that wants a map[string]string; use Pairs when order or duplicates matter.
// ExampleFile_Map returns the effective view: one value per key, last line
// wins, values raw (references not expanded).
func ExampleFile_Map() {
const content = `# database
DB_HOST=localhost
DB_PORT=5432
# DB_USER=admin
DB_HOST=db.internal
HOME
`
f := dotenv.Parse(content)
m := f.Map()
fmt.Println(len(m), m["DB_HOST"], m["DB_PORT"])
// Output:
// 2 db.internal 5432
}To see disabled settings and inherited names rather than skip them, use f.Disabled(), f.Inherited() or walk f.Entries() (see entries.md and editing.md).
Examples: ExampleFile_Get, ExampleFile_Has, ExampleFile_Count, ExampleFile_Keys, ExampleFile_Pairs, ExampleFile_Map.
Three facts describe a file's place on disk.
| Fact | Open of an existing file |
Open of a missing file |
Parse / ParseReader |
|---|---|---|---|
f.Existed() |
true |
false |
false |
f.Mode() |
the file's own permission bits | 0600 (-rw-------) |
0600 |
f.Path |
the path passed to Open |
the path passed to Open |
"" |
Existed tells a fresh file apart from one already on disk, for example to print "created .env" rather than "updated .env".
// ExampleFile_Existed tells a freshly created file apart from one that was
// already on disk. A File from Parse never existed on disk.
func ExampleFile_Existed() {
// envFile is the name the example writes inside its own temp directory.
const envFile = ".env"
dir, err := os.MkdirTemp("", "dotenv-existed")
if err != nil {
fmt.Println(err)
return
}
defer func() {
// Cleanup is best-effort; a failure goes to stderr so the example's
// checked stdout output is unaffected.
if err := os.RemoveAll(dir); err != nil {
fmt.Fprintln(os.Stderr, "cleanup:", err)
}
}()
path := filepath.Join(dir, envFile)
before, err := dotenv.Open(path)
if err != nil {
fmt.Println(err)
return
}
if err := os.WriteFile(path, []byte("A=1\n"), 0o600); err != nil {
fmt.Println(err)
return
}
after, err := dotenv.Open(path)
if err != nil {
fmt.Println(err)
return
}
fmt.Println("before writing:", before.Existed())
fmt.Println("after writing:", after.Existed())
fmt.Println("from Parse:", dotenv.Parse("A=1\n").Existed())
// Output:
// before writing: false
// after writing: true
// from Parse: false
}Mode is the permission set Save will apply. An existing file keeps its mode; a new one gets 0600, because a .env holds credentials and a group-readable secret is a leak.
// ExampleFile_Mode reports the permissions Save will apply: the file's own
// mode when it existed, 0600 for a file Save will create, because a .env holds
// credentials.
func ExampleFile_Mode() {
// sharedMode is a deliberately wider mode, to show Open keeps it.
const sharedMode fs.FileMode = 0o640
// envFile is the name the example writes inside its own temp directory.
const envFile = ".env"
dir, err := os.MkdirTemp("", "dotenv-mode")
if err != nil {
fmt.Println(err)
return
}
defer func() {
// Cleanup is best-effort; a failure goes to stderr so the example's
// checked stdout output is unaffected.
if err := os.RemoveAll(dir); err != nil {
fmt.Fprintln(os.Stderr, "cleanup:", err)
}
}()
path := filepath.Join(dir, envFile)
fresh, err := dotenv.Open(path)
if err != nil {
fmt.Println(err)
return
}
fmt.Println("missing file:", fresh.Mode())
if err := os.WriteFile(path, []byte("A=1\n"), sharedMode); err != nil {
fmt.Println(err)
return
}
// WriteFile's mode is filtered by the umask; set it exactly.
if err := os.Chmod(path, sharedMode); err != nil {
fmt.Println(err)
return
}
existing, err := dotenv.Open(path)
if err != nil {
fmt.Println(err)
return
}
fmt.Println("existing file:", existing.Mode())
// Output:
// missing file: -rw-------
// existing file: -rw-r-----
}Path is an exported field, not a method. Save writes to it, so you can retarget a File by assigning it. SaveAs writes elsewhere without changing it (see saving.md).
// ExampleFile_Path shows where Save writes: the path given to Open. Parse has
// no path, so Path starts empty and must be set before Save.
func ExampleFile_Path() {
// envFile is the name the example writes inside its own temp directory.
const envFile = ".env.local"
dir, err := os.MkdirTemp("", "dotenv-path")
if err != nil {
fmt.Println(err)
return
}
defer func() {
// Cleanup is best-effort; a failure goes to stderr so the example's
// checked stdout output is unaffected.
if err := os.RemoveAll(dir); err != nil {
fmt.Fprintln(os.Stderr, "cleanup:", err)
}
}()
opened, err := dotenv.Open(filepath.Join(dir, envFile))
if err != nil {
fmt.Println(err)
return
}
// Print only the base name: the temp directory differs on every run.
fmt.Println("Open:", filepath.Base(opened.Path))
parsed := dotenv.Parse("A=1\n")
fmt.Printf("Parse: %q\n", parsed.Path)
parsed.Path = filepath.Join(dir, envFile)
if err := parsed.Save(); err != nil {
fmt.Println(err)
return
}
data, err := os.ReadFile(parsed.Path)
if err != nil {
fmt.Println(err)
return
}
fmt.Printf("saved: %q\n", data)
// Output:
// Open: .env.local
// Parse: ""
// saved: "A=1\n"
}Examples: ExampleFile_Existed, ExampleFile_Mode, ExampleFile_Path.
Every snippet on this page is an Example function in example_read_test.go. go test runs each one and compares what it prints with its // Output: block, so the outputs shown above are checked on every run. From the repository root:
go test -run '^Example(Read|Open|Open_missing|Parse|ParseReader|File_(Get|Has|Count|Keys|Pairs|Map|Existed|Mode|Path))$' -v .=== RUN ExampleRead
--- PASS: ExampleRead (0.00s)
=== RUN ExampleOpen
--- PASS: ExampleOpen (0.00s)
=== RUN ExampleOpen_missing
--- PASS: ExampleOpen_missing (0.00s)
=== RUN ExampleParse
--- PASS: ExampleParse (0.00s)
=== RUN ExampleParseReader
--- PASS: ExampleParseReader (0.00s)
=== RUN ExampleFile_Get
--- PASS: ExampleFile_Get (0.00s)
=== RUN ExampleFile_Has
--- PASS: ExampleFile_Has (0.00s)
=== RUN ExampleFile_Count
--- PASS: ExampleFile_Count (0.00s)
=== RUN ExampleFile_Keys
--- PASS: ExampleFile_Keys (0.00s)
=== RUN ExampleFile_Pairs
--- PASS: ExampleFile_Pairs (0.00s)
=== RUN ExampleFile_Map
--- PASS: ExampleFile_Map (0.00s)
=== RUN ExampleFile_Existed
--- PASS: ExampleFile_Existed (0.00s)
=== RUN ExampleFile_Mode
--- PASS: ExampleFile_Mode (0.00s)
=== RUN ExampleFile_Path
--- PASS: ExampleFile_Path (0.00s)
PASS
ok github.com/ubgo/dotenv 0.010s
A passing Example prints nothing beyond PASS: the printed text matched its // Output: block exactly. Change an expected line in the file and run it again to see the diff go test reports.
The parser holds the whole file in memory. That is not an oversight: byte-exact rendering needs every original line, forward ${REF} references need the entries further down, and insertion needs an index into a complete entry list. ParseReader lowers the cost of getting the bytes in; nothing here streams.
What the test suite and benchmarks back:
- Parsing is linear in the file size.
TestParse_ScalesLinearlyparses a 1.25 MB and a 5 MB file of shortKEY_n=…lines and fails if quadrupling the input costs more than 9 times as long (linear is about 4 times, quadratic about 16). It also checks the 5 MB file yields over 100,000 keys and renders back byte for byte. It guards a real regression: pre-trimming the lookahead for every pair once made a 5 MB file take 23 seconds. The test is skipped undergo test -short. ParseReaderallocates less thanio.ReadAllthenParse.BenchmarkParseLargeparses a file of about 1.4 MB holding one huge quoted value. The measurement recorded in theParseReaderdoc comment is 9.8 MB and 67 allocations, against 13.0 MB and 93 forReadAllthenParse.- Per-entry cost is measured by
BenchmarkParseManyEntries(1 MB of short entries), the shape where the quadratic bug lived.
Benchmark numbers depend on the machine. Re-run them rather than trusting the figures above:
task bench
# or, without Task:
go test -run '^$' -bench . -benchmem .Readreturns expanded values;OpenandParsereturn raw ones. Writing a value fromReadorExpandedMapback withSetreplaces the${REF}with a copy of its target, and the link is lost. Read raw values withGetorMapwhen the file will be saved.Openof a missing file succeeds. A typo in the path gives an emptyFile, not an error. Checkf.Existed()when the file must already exist, or useRead, which fails on a missing file.- Duplicates are silent.
GetandMapquietly return the last line. RunCountoverKeys()(as inExampleFile_Count) if a duplicate should be reported. Geton a commented-out setting reports not found.# DB_USER=adminis inactive. Usef.Disabled()to tell "disabled" apart from "missing".- A name-only line is not a value.
HOMEon its own line declares a variable inherited from the environment. The library never reads the environment, soGet("HOME")is"", false; usef.Inherited()and applyos.LookupEnvyourself. - A malformed pair disappears from every accessor.
MY KEY=value(a space in the key) is an unrecognised line, not an error; walkEntries()and flagKindOtherif you want strictness (see entries.md). Parsegives an emptyPath. CallingSaveon it before assigningPathfails; setf.Pathor useSaveAs.Readexpansion can fail. A${VAR:?message}whose variable is unset makesReadandExpandedMapreturn an error and no map. See expansion.md.
- entries.md — the
Entrytype, the six kinds, and walkingEntries(). - editing.md —
Set,Unset,Restore,Disabled,Inherited. - saving.md —
Save,SaveAs, modes and line endings. - syntax.md — quoting, comments and escapes, line by line.
- expansion.md —
GetExpanded,ExpandedMapand every${…}form. - Feature index — every library feature with its guide and example.
- Examples:
example_read_test.go.