Awesome Open Source
Awesome Open Source


godoc semver tag go report card coverage status license


fig is a tiny library for loading an application's config file and its environment into a Go struct. Individual fields can have default values defined or be marked as required.

Why fig?

  • Define your configuration, validations and defaults in a single location
  • Optionally load from the environment as well
  • Only 3 external dependencies
  • Full support fortime.Time, time.Duration & regexp.Regexp
  • Tiny API
  • Decoders for .yaml, .json and .toml files

Getting Started

$ go get -d

Define your config file:

# config.yaml

build: "2020-01-09T12:30:00Z"

      - 8080
    cleanup: 1h

    level: "warn"
    trace: true

Define your struct along with validations or defaults:

package main

import (


type Config struct {
  Build  time.Time `fig:"build" validate:"required"`
  Server struct {
    Host    string        `fig:"host" default:""`
    Ports   []int         `fig:"ports" default:"[80,443]"`
    Cleanup time.Duration `fig:"cleanup" default:"30m"`
  Logger struct {
    Level   string         `fig:"level" default:"info"`
    Pattern *regexp.Regexp `fig:"pattern" default:".*"`
    Trace   bool           `fig:"trace"`

func main() {
  var cfg Config
  err := fig.Load(&cfg)
  // handle your err
  fmt.Printf("%+v\n", cfg)
  // Output: {Build:2019-12-25 00:00:00 +0000 UTC Server:{Host: Ports:[8080] Cleanup:1h0m0s} Logger:{Level:warn Pattern:.* Trace:true}}

If a field is not set and is marked as required then an error is returned. If a default value is defined instead then that value is used to populate the field.

Fig searches for a file named config.yaml in the directory it is run from. Change the lookup behaviour by passing additional parameters to Load():

  fig.Dirs(".", "/etc/myapp", "/home/user/myapp"),
) // searches for ./settings.json, /etc/myapp/settings.json, /home/user/myapp/settings.json


Need to additionally fill fields from the environment? It's as simple as:

fig.Load(&cfg, fig.UseEnv("MYAPP"))


See usage examples.


See for detailed documentation.


PRs are welcome! Please explain your motivation for the change in your PR and ensure your change is properly tested and documented.

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Go (194,257
Golang (32,223
Json (10,998
Configuration (2,525
Yaml (2,008
Environment (941
Configuration Management (783
Environment Variables (621
Toml (302
Related Projects