README.md (3997B)
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 8 Load environment variables from `.env` or `io.Reader` in Go. 9 10 ## Usage 11 12 Put the gotenv package on your `import` statement: 13 14 ```go 15 import "github.com/subosito/gotenv" 16 ``` 17 18 To modify your app environment variables, `gotenv` expose 2 main functions: 19 20 - `gotenv.Load` 21 - `gotenv.Apply` 22 23 By default, `gotenv.Load` will look for a file called `.env` in the current working directory. 24 25 Behind 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 27 Once loaded you can use `os.Getenv()` to get the value of the variable. 28 29 Let's say you have `.env` file: 30 31 ```sh 32 APP_ID=1234567 33 APP_SECRET=abcdef 34 ``` 35 36 Here's the example of your app: 37 38 ```go 39 package main 40 41 import ( 42 "github.com/subosito/gotenv" 43 "log" 44 "os" 45 ) 46 47 func init() { 48 gotenv.Load() 49 } 50 51 func main() { 52 log.Println(os.Getenv("APP_ID")) // "1234567" 53 log.Println(os.Getenv("APP_SECRET")) // "abcdef" 54 } 55 ``` 56 57 You 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 60 gotenv.Load(".env.production", "credentials") 61 ``` 62 63 While `gotenv.Load` loads entries from `.env` file, `gotenv.Apply` allows you to use any `io.Reader`: 64 65 ```go 66 gotenv.Apply(strings.NewReader("APP_ID=1234567")) 67 68 log.Println(os.Getenv("APP_ID")) 69 // Output: "1234567" 70 ``` 71 72 Both `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 76 Besides above functions, `gotenv` also provides another functions that overrides existing: 77 78 - `gotenv.OverLoad` 79 - `gotenv.OverApply` 80 81 Here's the example of this overrides behavior: 82 83 ```go 84 os.Setenv("HELLO", "world") 85 86 // NOTE: using Apply existing value will be reserved 87 gotenv.Apply(strings.NewReader("HELLO=universe")) 88 fmt.Println(os.Getenv("HELLO")) 89 // Output: "world" 90 91 // NOTE: using OverApply existing value will be overridden 92 gotenv.OverApply(strings.NewReader("HELLO=universe")) 93 fmt.Println(os.Getenv("HELLO")) 94 // Output: "universe" 95 ``` 96 97 ### Throw a Panic 98 99 Both `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 102 err := gotenv.Load(".env-is-not-exist") 103 fmt.Println("error", err) 104 // error: open .env-is-not-exist: no such file or directory 105 106 gotenv.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 113 Just 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 118 pairs := gotenv.Parse(strings.NewReader("FOO=test\nBAR=$FOO")) 119 // gotenv.Env{"FOO": "test", "BAR": "test"} 120 121 pairs, 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 129 The 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.