1# gotenv
2
3[](https://github.com/subosito/gotenv/actions)
4[](https://codecov.io/gh/subosito/gotenv)
5[](https://goreportcard.com/report/github.com/subosito/gotenv)
6[](https://godoc.org/github.com/subosito/gotenv)
7
8Load environment variables from `.env` or `io.Reader` in Go.
9
10## Usage
11
12Put the gotenv package on your `import` statement:
13
14```go
15import "github.com/subosito/gotenv"
16```
17
18To modify your app environment variables, `gotenv` expose 2 main functions:
19
20- `gotenv.Load`
21- `gotenv.Apply`
22
23By default, `gotenv.Load` will look for a file called `.env` in the current working directory.
24
25Behind the scene, it will then load `.env` file and export the valid variables to the environment variables. Make sure you call the method as soon as possible to ensure it loads all variables, say, put it on `init()` function.
26
27Once loaded you can use `os.Getenv()` to get the value of the variable.
28
29Let's say you have `.env` file:
30
31```sh
32APP_ID=1234567
33APP_SECRET=abcdef
34```
35
36Here's the example of your app:
37
38```go
39package main
40
41import (
42 "github.com/subosito/gotenv"
43 "log"
44 "os"
45)
46
47func init() {
48 gotenv.Load()
49}
50
51func main() {
52 log.Println(os.Getenv("APP_ID")) // "1234567"
53 log.Println(os.Getenv("APP_SECRET")) // "abcdef"
54}
55```
56
57You can also load other than `.env` file if you wish. Just supply filenames when calling `Load()`. It will load them in order and the first value set for a variable will win.:
58
59```go
60gotenv.Load(".env.production", "credentials")
61```
62
63While `gotenv.Load` loads entries from `.env` file, `gotenv.Apply` allows you to use any `io.Reader`:
64
65```go
66gotenv.Apply(strings.NewReader("APP_ID=1234567"))
67
68log.Println(os.Getenv("APP_ID"))
69// Output: "1234567"
70```
71
72Both `gotenv.Load` and `gotenv.Apply` **DO NOT** overrides existing environment variables. If you want to override existing ones, you can see section below.
73
74### Environment Overrides
75
76Besides above functions, `gotenv` also provides another functions that overrides existing:
77
78- `gotenv.OverLoad`
79- `gotenv.OverApply`
80
81Here's the example of this overrides behavior:
82
83```go
84os.Setenv("HELLO", "world")
85
86// NOTE: using Apply existing value will be reserved
87gotenv.Apply(strings.NewReader("HELLO=universe"))
88fmt.Println(os.Getenv("HELLO"))
89// Output: "world"
90
91// NOTE: using OverApply existing value will be overridden
92gotenv.OverApply(strings.NewReader("HELLO=universe"))
93fmt.Println(os.Getenv("HELLO"))
94// Output: "universe"
95```
96
97### Throw a Panic
98
99Both `gotenv.Load` and `gotenv.OverLoad` returns an error on something wrong occurred, like your env file is not exist, and so on. To make it easier to use, `gotenv` also provides `gotenv.Must` helper, to let it panic when an error returned.
100
101```go
102err := gotenv.Load(".env-is-not-exist")
103fmt.Println("error", err)
104// error: open .env-is-not-exist: no such file or directory
105
106gotenv.Must(gotenv.Load, ".env-is-not-exist")
107// it will throw a panic
108// panic: open .env-is-not-exist: no such file or directory
109```
110
111### Another Scenario
112
113Just in case you want to parse environment variables from any `io.Reader`, gotenv keeps its `Parse` and `StrictParse` function as public API so you can use that.
114
115```go
116// import "strings"
117
118pairs := gotenv.Parse(strings.NewReader("FOO=test\nBAR=$FOO"))
119// gotenv.Env{"FOO": "test", "BAR": "test"}
120
121pairs, err := gotenv.StrictParse(strings.NewReader(`FOO="bar"`))
122// gotenv.Env{"FOO": "bar"}
123```
124
125`Parse` ignores invalid lines and returns `Env` of valid environment variables, while `StrictParse` returns an error for invalid lines.
126
127## Notes
128
129The gotenv package is a Go port of [`dotenv`](https://github.com/bkeepers/dotenv) project with some additions made for Go. For general features, it aims to be compatible as close as possible.
View as plain text