Go library for the TOML format.

This library supports TOML version v0.5.0

Programming language: Go
License: GNU General Public License v3.0 or later
Tags: Utilities     Productivity     Configuration     Go     Golang    
Latest version: v1.8.1

go-toml alternatives and similar packages

Based on the "Configuration" category.
Alternatively, view go-toml alternatives based on common mentions on social networks and blogs.

Do you think we are missing an alternative of go-toml or a related project?

Add another 'Configuration' Package



Go library for the TOML format.

This library supports TOML version v1.0.0-rc.3

Go Reference license Build Status codecov Go Report Card FOSSA Status

Development status

ℹ️ Consider go-toml v2!

The next version of go-toml is in active development, and nearing completion.

Though technically in beta, v2 is already more tested, fixes bugs, and much faster. If you only need reading and writing TOML documents (majority of cases), those features are implemented and the API unlikely to change.

The remaining features (Document structure editing and tooling) will be added shortly. While pull-requests are welcome on v1, no active development is expected on it. When v2.0.0 is released, v1 will be deprecated.

👉 go-toml v2


Go-toml provides the following features for using data parsed from TOML documents:

  • Load TOML documents from files and string data
  • Easily navigate TOML structure using Tree
  • Marshaling and unmarshaling to and from data structures
  • Line & column position data for all parsed elements
  • [Query support similar to JSON-Path](query/)
  • Syntax errors contain line and column numbers


import "github.com/pelletier/go-toml"

Usage example

Read a TOML document:

config, _ := toml.Load(`
user = "pelletier"
password = "mypassword"`)
// retrieve data directly
user := config.Get("postgres.user").(string)

// or using an intermediate object
postgresConfig := config.Get("postgres").(*toml.Tree)
password := postgresConfig.Get("password").(string)

Or use Unmarshal:

type Postgres struct {
    User     string
    Password string
type Config struct {
    Postgres Postgres

doc := []byte(`
User = "pelletier"
Password = "mypassword"`)

config := Config{}
toml.Unmarshal(doc, &config)
fmt.Println("user=", config.Postgres.User)

Or use a query:

// use a query to gather elements without walking the tree
q, _ := query.Compile("$..[user,password]")
results := q.Execute(config)
for ii, item := range results.Values() {
    fmt.Printf("Query result %d: %v\n", ii, item)


The documentation and additional examples are available at pkg.go.dev.


Go-toml provides three handy command line tools:

  • tomll: Reads TOML files and lints them.

    go install github.com/pelletier/go-toml/cmd/tomll
    tomll --help
  • tomljson: Reads a TOML file and outputs its JSON representation.

    go install github.com/pelletier/go-toml/cmd/tomljson
    tomljson --help
    • jsontoml: Reads a JSON file and outputs a TOML representation.
    go install github.com/pelletier/go-toml/cmd/jsontoml
    jsontoml --help

Docker image

Those tools are also available as a Docker image from dockerhub. For example, to use tomljson:

docker run -v $PWD:/workdir pelletier/go-toml tomljson /workdir/example.toml

Only master (latest) and tagged versions are published to dockerhub. You can build your own image as usual:

docker build -t go-toml .


Feel free to report bugs and patches using GitHub's pull requests system on pelletier/go-toml. Any feedback would be much appreciated!

Run tests

go test ./...


The script ./fuzz.sh is available to run go-fuzz on go-toml.


Go-toml follows Semantic Versioning. The supported version of TOML is indicated at the beginning of this document. The last two major versions of Go are supported (see Go Release Policy).


The MIT License (MIT) + Apache 2.0. Read [LICENSE](LICENSE).

*Note that all licence references and agreements mentioned in the go-toml README section above are relevant to that project's source code only.