1# GoDotEnv  [](https://goreportcard.com/report/github.com/joho/godotenv)
2
3A Go (golang) port of the Ruby [dotenv](https://github.com/bkeepers/dotenv) project (which loads env vars from a .env file).
4
5From the original Library:
6
7> Storing configuration in the environment is one of the tenets of a twelve-factor app. Anything that is likely to change between deployment environments–such as resource handles for databases or credentials for external services–should be extracted from the code into environment variables.
8>
9> But it is not always practical to set environment variables on development machines or continuous integration servers where multiple projects are run. Dotenv load variables from a .env file into ENV when the environment is bootstrapped.
10
11It can be used as a library (for loading in env for your own daemons etc.) or as a bin command.
12
13There is test coverage and CI for both linuxish and Windows environments, but I make no guarantees about the bin version working on Windows.
14
15## Installation
16
17As a library
18
19```shell
20go get github.com/joho/godotenv
21```
22
23or if you want to use it as a bin command
24
25go >= 1.17
26```shell
27go install github.com/joho/godotenv/cmd/godotenv@latest
28```
29
30go < 1.17
31```shell
32go get github.com/joho/godotenv/cmd/godotenv
33```
34
35## Usage
36
37Add your application configuration to your `.env` file in the root of your project:
38
39```shell
40S3_BUCKET=YOURS3BUCKET
41SECRET_KEY=YOURSECRETKEYGOESHERE
42```
43
44Then in your Go app you can do something like
45
46```go
47package main
48
49import (
50 "log"
51 "os"
52
53 "github.com/joho/godotenv"
54)
55
56func main() {
57 err := godotenv.Load()
58 if err != nil {
59 log.Fatal("Error loading .env file")
60 }
61
62 s3Bucket := os.Getenv("S3_BUCKET")
63 secretKey := os.Getenv("SECRET_KEY")
64
65 // now do something with s3 or whatever
66}
67```
68
69If you're even lazier than that, you can just take advantage of the autoload package which will read in `.env` on import
70
71```go
72import _ "github.com/joho/godotenv/autoload"
73```
74
75While `.env` in the project root is the default, you don't have to be constrained, both examples below are 100% legit
76
77```go
78godotenv.Load("somerandomfile")
79godotenv.Load("filenumberone.env", "filenumbertwo.env")
80```
81
82If you want to be really fancy with your env file you can do comments and exports (below is a valid env file)
83
84```shell
85# I am a comment and that is OK
86SOME_VAR=someval
87FOO=BAR # comments at line end are OK too
88export BAR=BAZ
89```
90
91Or finally you can do YAML(ish) style
92
93```yaml
94FOO: bar
95BAR: baz
96```
97
98as a final aside, if you don't want godotenv munging your env you can just get a map back instead
99
100```go
101var myEnv map[string]string
102myEnv, err := godotenv.Read()
103
104s3Bucket := myEnv["S3_BUCKET"]
105```
106
107... or from an `io.Reader` instead of a local file
108
109```go
110reader := getRemoteFile()
111myEnv, err := godotenv.Parse(reader)
112```
113
114... or from a `string` if you so desire
115
116```go
117content := getRemoteFileContent()
118myEnv, err := godotenv.Unmarshal(content)
119```
120
121### Precedence & Conventions
122
123Existing envs take precedence of envs that are loaded later.
124
125The [convention](https://github.com/bkeepers/dotenv#what-other-env-files-can-i-use)
126for managing multiple environments (i.e. development, test, production)
127is to create an env named `{YOURAPP}_ENV` and load envs in this order:
128
129```go
130env := os.Getenv("FOO_ENV")
131if "" == env {
132 env = "development"
133}
134
135godotenv.Load(".env." + env + ".local")
136if "test" != env {
137 godotenv.Load(".env.local")
138}
139godotenv.Load(".env." + env)
140godotenv.Load() // The Original .env
141```
142
143If you need to, you can also use `godotenv.Overload()` to defy this convention
144and overwrite existing envs instead of only supplanting them. Use with caution.
145
146### Command Mode
147
148Assuming you've installed the command as above and you've got `$GOPATH/bin` in your `$PATH`
149
150```
151godotenv -f /some/path/to/.env some_command with some args
152```
153
154If you don't specify `-f` it will fall back on the default of loading `.env` in `PWD`
155
156By default, it won't override existing environment variables; you can do that with the `-o` flag.
157
158### Writing Env Files
159
160Godotenv can also write a map representing the environment to a correctly-formatted and escaped file
161
162```go
163env, err := godotenv.Unmarshal("KEY=value")
164err := godotenv.Write(env, "./.env")
165```
166
167... or to a string
168
169```go
170env, err := godotenv.Unmarshal("KEY=value")
171content, err := godotenv.Marshal(env)
172```
173
174## Contributing
175
176Contributions are welcome, but with some caveats.
177
178This library has been declared feature complete (see [#182](https://github.com/joho/godotenv/issues/182) for background) and will not be accepting issues or pull requests adding new functionality or breaking the library API.
179
180Contributions would be gladly accepted that:
181
182* bring this library's parsing into closer compatibility with the mainline dotenv implementations, in particular [Ruby's dotenv](https://github.com/bkeepers/dotenv) and [Node.js' dotenv](https://github.com/motdotla/dotenv)
183* keep the library up to date with the go ecosystem (ie CI bumps, documentation changes, changes in the core libraries)
184* bug fixes for use cases that pertain to the library's purpose of easing development of codebases deployed into twelve factor environments
185
186*code changes without tests and references to peer dotenv implementations will not be accepted*
187
1881. Fork it
1892. Create your feature branch (`git checkout -b my-new-feature`)
1903. Commit your changes (`git commit -am 'Added some feature'`)
1914. Push to the branch (`git push origin my-new-feature`)
1925. Create new Pull Request
193
194## Releases
195
196Releases should follow [Semver](http://semver.org/) though the first couple of releases are `v1` and `v1.1`.
197
198Use [annotated tags for all releases](https://github.com/joho/godotenv/issues/30). Example `git tag -a v1.2.1`
199
200## Who?
201
202The original library [dotenv](https://github.com/bkeepers/dotenv) was written by [Brandon Keepers](http://opensoul.org/), and this port was done by [John Barton](https://johnbarton.co/) based off the tests/fixtures in the original library.