go-toml v2

June 16, 2026 · View on GitHub

Go library for the TOML format.

This library supports TOML v1.1.0.

🐞 Bug Reports

💬 Anything else

Documentation

Full API, examples, and implementation notes are available in the Go documentation.

Go Reference

Import

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

Features

Stdlib behavior

As much as possible, this library is designed to behave similarly as the standard library's encoding/json.

When encoding structs, fields tagged with omitempty are omitted if they are empty. For time.Time, the zero value is considered empty, so timestamps such as created_at or updated_at are not written unless you remove omitempty from the struct tag or use a pointer type (*time.Time).

Performance

While go-toml favors usability, it is written with performance in mind. Most operations should not be shockingly slow. See benchmarks.

Strict mode

Decoder can be set to "strict mode", which makes it error when some parts of the TOML document was not present in the target structure. This is a great way to check for typos. See example in the documentation.

Contextualized errors

When most decoding errors occur, go-toml returns DecodeError, which contains a human readable contextualized version of the error. For example:

1| [server]
2| path = 100
 |        ~~~ cannot decode TOML integer into struct field toml_test.Server.Path of type string
3| port = 50

Local date and time support

TOML supports native local date/times. It allows to represent a given date, time, or date-time without relation to a timezone or offset. To support this use-case, go-toml provides LocalDate, LocalTime, and LocalDateTime. Those types can be transformed to and from time.Time, making them convenient yet unambiguous structures for their respective TOML representation.

Commented config

Since TOML is often used for configuration files, go-toml can emit documents annotated with comments and commented-out values. For example, it can generate the following file:

# Host IP to connect to.
host = '127.0.0.1'
# Port of the remote server.
port = 4242

# Encryption parameters (optional)
# [TLS]
# cipher = 'AEAD-AES128-GCM-SHA256'
# version = 'TLS 1.3'

Getting started

Given the following struct, let's see how to read it and write it as TOML:

type MyConfig struct {
	Version int
	Name    string
	Tags    []string
}

Unmarshaling

Unmarshal reads a TOML document and fills a Go structure with its content.

Note that the struct variable names are capitalized, while the variables in the toml document are lowercase.

For example:

doc := `
version = 2
name = "go-toml"
tags = ["go", "toml"]
`

var cfg MyConfig
err := toml.Unmarshal([]byte(doc), &cfg)
if err != nil {
	panic(err)
}
fmt.Println("version:", cfg.Version)
fmt.Println("name:", cfg.Name)
fmt.Println("tags:", cfg.Tags)

// Output:
// version: 2
// name: go-toml
// tags: [go toml]

Here is an example using tables with some simple nesting:

doc := `
age = 45
fruits = ["apple", "pear"]

# these are very important!
[my-variables]
first = 1
second = 0.2
third = "abc"

# this is not so important.
[my-variables.b]
bfirst = 123
`

var Document struct {
	Age int
	Fruits []string

	Myvariables struct {
		First  int
		Second float64
		Third  string

		B struct {
			Bfirst int
		}
	} `toml:"my-variables"`
}

err := toml.Unmarshal([]byte(doc), &Document)
if err != nil {
	panic(err)
}

fmt.Println("age:", Document.Age)
fmt.Println("fruits:", Document.Fruits)
fmt.Println("my-variables.first:", Document.Myvariables.First)
fmt.Println("my-variables.second:", Document.Myvariables.Second)
fmt.Println("my-variables.third:", Document.Myvariables.Third)
fmt.Println("my-variables.B.Bfirst:", Document.Myvariables.B.Bfirst)

// Output:
// age: 45
// fruits: [apple pear]
// my-variables.first: 1
// my-variables.second: 0.2
// my-variables.third: abc
// my-variables.B.Bfirst: 123

Marshaling

Marshal is the opposite of Unmarshal: it represents a Go structure as a TOML document:

cfg := MyConfig{
	Version: 2,
	Name:    "go-toml",
	Tags:    []string{"go", "toml"},
}

b, err := toml.Marshal(cfg)
if err != nil {
	panic(err)
}
fmt.Println(string(b))

// Output:
// Version = 2
// Name = 'go-toml'
// Tags = ['go', 'toml']

Unstable API

This API does not yet follow the backward compatibility guarantees of this library. They provide early access to features that may have rough edges or an API subject to change.

Parser

Parser is the unstable API that allows iterative parsing of a TOML document at the AST level. See https://pkg.go.dev/github.com/pelletier/go-toml/v2/unstable.

Benchmarks

Execution time speedup compared to other Go TOML libraries:

Benchmarkgo-toml v1BurntSushi/toml
Marshal/HugoFrontMatter-22.3x2.4x
Marshal/ReferenceFile/map-22.2x2.6x
Marshal/ReferenceFile/struct-24.9x5.0x
Unmarshal/HugoFrontMatter-27.8x5.9x
Unmarshal/ReferenceFile/map-26.8x6.4x
Unmarshal/ReferenceFile/struct-26.8x6.3x
See more

The table above has the results of the most common use-cases. The table below contains the results of all benchmarks, including unrealistic ones. It is provided for completeness.

Benchmarkgo-toml v1BurntSushi/toml
Marshal/SimpleDocument/map-22.1x3.1x
Marshal/SimpleDocument/struct-23.4x4.8x
Unmarshal/SimpleDocument/map-210.1x7.0x
Unmarshal/SimpleDocument/struct-212.4x8.0x
UnmarshalDataset/example-28.2x6.9x
UnmarshalDataset/code-27.5x8.3x
UnmarshalDataset/twitter-29.0x7.6x
UnmarshalDataset/citm_catalog-25.0x4.5x
UnmarshalDataset/canada-26.4x4.7x
UnmarshalDataset/config-210.2x6.1x
geomean5.8x5.3x

This table can be generated with ./ci.sh benchmark -a -html.

Tools

Go-toml provides three handy command line tools:

  • tomljson: Reads a TOML file and outputs its JSON representation.

    $ go install github.com/pelletier/go-toml/v2/cmd/tomljson@latest
$ tomljson --help

  • jsontoml: Reads a JSON file and outputs a TOML representation.

    $ go install github.com/pelletier/go-toml/v2/cmd/jsontoml@latest
$ jsontoml --help

  • tomll: Lints and reformats a TOML file.

    $ go install github.com/pelletier/go-toml/v2/cmd/tomll@latest
$ tomll --help

Docker image

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

docker run -i ghcr.io/pelletier/go-toml:v2 tomljson < example.toml

Multiple versions are available on ghcr.io.

Versioning

Expect for parts explicitly marked otherwise, 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).

License

The MIT License (MIT). Read LICENSE.