Go library for the TOML format.

This library supports TOML version v0.4.0

GoDoc License Build Status Coverage Status Go Report Card


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 TomlTree
  • Line & column position data for all parsed elements
  • Query support similar to JSON-Path
  • Syntax errors contain line and column numbers

Go-toml is designed to help cover use-cases not covered by reflection-based TOML parsing:

  • Semantic evaluation of parsed TOML
  • Informing a user of mistakes in the source document, after it has been parsed
  • Programatic handling of default values on a case-by-case basis
  • Using a TOML document as a flexible data-store


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



Say you have a TOML file that looks like this:

user = "pelletier"
password = "mypassword"

Read the username and password like this:

import (

config, err := toml.LoadFile("config.toml")
if err != nil {
    fmt.Println("Error ", err.Error())
} else {
    // retrieve data directly
    user := config.Get("postgres.user").(string)
    password := config.Get("postgres.password").(string)

    // or using an intermediate object
    configTree := config.Get("postgres").(*toml.TomlTree)
    user = configTree.Get("user").(string)
    password = configTree.Get("password").(string)
    fmt.Println("User is ", user, ". Password is ", password)

    // show where elements are in the file
    fmt.Println("User position: %v", configTree.GetPosition("user"))
    fmt.Println("Password position: %v", configTree.GetPosition("password"))

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


The documentation and additional examples are available at godoc.org.


Go-toml provides two handy command line tools:

  • tomll: Reads TOML files and lint 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/tomjson
    tomljson --help


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

You have to make sure two kind of tests run:

  1. The Go unit tests
  2. The TOML examples base

You can run both of them using ./test.sh.


The MIT License (MIT). Read LICENSE.