Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.

TOML parser and encoder library for Golang Build Status

TOML parser and encoder library for Golang.

This library is compatible with TOML version v0.4.0.


go get -u


The following TOML save as example.toml.

# This is a TOML document. Boom.

title = "TOML Example"

name = "Lance Uppercut"
dob = 1979-05-27T07:32:00-08:00 # First class dates? Why not?

server = ""
ports = [ 8001, 8001, 8002 ]
connection_max = 5000
enabled = true


  # You can indent as you please. Tabs or spaces. TOML don't care.
  ip = ""
  dc = "eqdc10"

  ip = ""
  dc = "eqdc10"

data = [ ["gamma", "delta"], [1, 2] ]

# Line breaks are OK when inside arrays
hosts = [

Then above TOML will mapping to tomlConfig struct using toml.Unmarshal.

package main

import (


type tomlConfig struct {
    Title string
    Owner struct {
        Name string
        Dob  time.Time
    Database struct {
        Server        string
        Ports         []int
        ConnectionMax uint
        Enabled       bool
    Servers map[string]ServerInfo
    Clients struct {
        Data  [][]interface{}
        Hosts []string

type ServerInfo struct {
    IP net.IP
    DC string

func main() {
    f, err := os.Open("example.toml")
    if err != nil {
    defer f.Close()
    var config tomlConfig
    if err := toml.NewDecoder(f).Decode(&config); err != nil {

    // then to use the unmarshaled config...
    fmt.Println("IP of server 'alpha':", config.Servers["alpha"].IP)


A key and value of TOML will map to the corresponding field. The fields of struct for mapping must be exported.

The rules of the mapping of key are following:

Exact matching

timeout_seconds = 256
type Config struct {
	Timeout_seconds int

Camelcase matching

server_name = "srv1"
type Config struct {
	ServerName string

Uppercase matching

ip = ""
type Config struct {
	IP string

See the following examples for the value mappings.


val = "string"
type Config struct {
	Val string


val = 100
type Config struct {
	Val int

All types that can be used are following:

  • int8 (from -128 to 127)
  • int16 (from -32768 to 32767)
  • int32 (from -2147483648 to 2147483647)
  • int64 (from -9223372036854775808 to 9223372036854775807)
  • int (same as int32 on 32bit environment, or int64 on 64bit environment)
  • uint8 (from 0 to 255)
  • uint16 (from 0 to 65535)
  • uint32 (from 0 to 4294967295)
  • uint64 (from 0 to 18446744073709551615)
  • uint (same as uint32 on 32bit environment, or uint64 on 64bit environment)


val = 3.1415
type Config struct {
	Val float32

All types that can be used are following:

  • float32
  • float64


val = true
type Config struct {
	Val bool


val = 2014-09-28T21:27:39Z
type Config struct {
	Val time.Time


val = ["a", "b", "c"]
type Config struct {
	Val []string

Also following examples all can be mapped:

val1 = [1, 2, 3]
val2 = [["a", "b"], ["c", "d"]]
val3 = [[1, 2, 3], ["a", "b", "c"]]
val4 = [[1, 2, 3], [["a", "b"], [true, false]]]
type Config struct {
	Val1 []int
	Val2 [][]string
	Val3 [][]interface{}
	Val4 [][]interface{}


type = "app"

  ip = ""

  ip = ""
type Config struct {
	Server map[string]Server

type Server struct {
	IP string

You can also use the following struct instead of map of struct.

type Config struct {
	Server struct {
		Development Server
		Production Server

type Server struct {
	IP string

Array of Tables

  name = "apple"

    color = "red"
    shape = "round"

    name = "red delicious"

    name = "granny smith"

  name = "banana"

    name = "plantain"
type Config struct {
	Fruit []struct {
		Name string
		Physical struct {
			Color string
			Shape string
		Variety []struct {
			Name string

Using the encoding.TextUnmarshaler interface

Package toml supports encoding.TextUnmarshaler (and encoding.TextMarshaler). You can use it to apply custom marshaling rules for certain types. The UnmarshalText method is called with the value text found in the TOML input. TOML strings are passed unquoted.

duration = "10s"
import time

type Duration time.Duration

// UnmarshalText implements encoding.TextUnmarshaler
func (d *Duration) UnmarshalText(data []byte) error {
    duration, err := time.ParseDuration(string(data))
    if err == nil {
        *d = Duration(duration)
    return err

// MarshalText implements encoding.TextMarshaler
func (d Duration) MarshalText() ([]byte, error) {
    return []byte(time.Duration(d).String()), nil

type ConfigWithDuration struct {
    Duration Duration

Using the toml.UnmarshalerRec interface

You can also override marshaling rules specifically for TOML using the UnmarshalerRec and MarshalerRec interfaces. These are useful if you want to control how structs or arrays are handled. You can apply additional validation or set unexported struct fields.

Note: encoding.TextUnmarshaler and encoding.TextMarshaler should be preferred for simple (scalar) values because they're also compatible with other formats like JSON or YAML.

See the UnmarshalerRec example.

Using the toml.Unmarshaler interface

If you want to deal with raw TOML syntax, use the Unmarshaler and Marshaler interfaces. Their input and output is raw TOML syntax. As such, these interfaces are useful if you want to handle TOML at the syntax level.

See the Unmarshaler example.

API documentation

See Godoc.




TOML parser and encoder library for Golang







No packages published