API Reference

This page provides a detailed reference for the public functions in the godotenv package.

func Load(filenames ...string) error

Loads environment variables from one or more files. If no filenames are provided, it defaults to loading .env from the current directory.

Key Behavior:

  • It will not override an environment variable that already exists.
  • Files are processed in the order they are provided. If a variable exists in multiple files, the value from the first file is used.

Example: 

// Load .env from the current directory
err := godotenv.Load()
if err != nil {
    log.Fatal("Error loading .env file")
}

// Load multiple specific files
err = godotenv.Load(".env.production", ".env.secrets")

func Overload(filenames ...string) error

Behaves identically to Load but will override any environment variables that already exist in the environment.

Example: 

// Assume FOO=bar is set in the shell environment
// .env contains FOO=baz

godotenv.Overload() // Loads .env

// Now, os.Getenv("FOO") will return "baz"

func Read(filenames ...string) (map[string]string, error)

Reads variables from one or more files into a map[string]string instead of loading them into the environment. If no filenames are given, it defaults to .env.

Example: 

env, err := godotenv.Read("config.env")
if err != nil {
    // handle error
}
apiKey := env["API_KEY"]

func Parse(r io.Reader) (map[string]string, error)

Reads and parses environment variables from an io.Reader and returns them as a map[string]string.

Example: 

import "strings"

fileContent := "GREETING=Hello\nTARGET=World"
reader := strings.NewReader(fileContent)

env, err := godotenv.Parse(reader)
// env["GREETING"] will be "Hello"

func Unmarshal(str string) (map[string]string, error)

Parses environment variables from a string and returns them as a map[string]string.

Example: 

rawEnv := "VERSION=1.2.3\nDB_HOST=localhost"
env, err := godotenv.Unmarshal(rawEnv)
// env["VERSION"] will be "1.2.3"

func UnmarshalBytes(src []byte) (map[string]string, error)

Parses environment variables from a byte slice ([]byte) and returns them as a map[string]string.

Example: 

rawEnvBytes := []byte("ENABLED=true")
env, err := godotenv.UnmarshalBytes(rawEnvBytes)
// env["ENABLED"] will be "true"

func Write(envMap map[string]string, filename string) error

Serializes a map[string]string into the .env format and writes it to the specified file. Keys are sorted, and values are properly quoted and escaped.

Example: 

env := map[string]string{
    "DB_USER": "admin",
    "DB_PASS": "p@ss#word",
}

err := godotenv.Write(env, ".env.generated")

func Marshal(envMap map[string]string) (string, error)

Serializes a map[string]string into a .env formatted string.

Example: 

env := map[string]string{"KEY": "some value"}

content, err := godotenv.Marshal(env)
// content will be `KEY="some value"`

func Exec(filenames []string, cmd string, cmdArgs []string, overload bool) error

Loads environment variables from specified files and then executes a command. It's a utility function for the CLI tool. For programmatic use, it is often better to use Load() or Overload() and the os/exec package directly for more control.

Parameters:

  • filenames: A slice of .env file paths to load.
  • cmd: The command to execute.
  • cmdArgs: The arguments for the command.
  • overload: If true, uses Overload() logic; otherwise, uses Load().