TOML · The Julia Language
Description: Documentation for The Julia Language.

# TOML

TOML.jl is a Julia standard library for parsing and writing [TOML v1.0](https://toml.io/en/) files.

## Parsing TOML data

    julia> using TOML

    julia> data = """
               [database]
               server = "192.168.1.1"
               ports = [ 8001, 8001, 8002 ]
           """;

    julia> TOML.parse(data)
    Dict{String, Any} with 1 entry:
      "database" => Dict{String, Any}("server"=>"192.168.1.1", "ports"=>[8001, 8001…

To parse a file, use `TOML.parsefile`. If the file has a syntax error, an exception is thrown:

    julia> using TOML

    julia> TOML.parse("""
               value = 0.0.0
           """)
    ERROR: TOML Parser error:
    none:1:16 error: failed to parse value
          value = 0.0.0
                     ^
    [...]

There are other versions of the parse functions (`TOML.tryparse` and `TOML.tryparsefile`) that instead of throwing exceptions on parser error returns a `TOML.ParserError` with information:

    julia> using TOML

    julia> err = TOML.tryparse("""
               value = 0.0.0
           """);

    julia> err.type
    ErrGenericValueError::ErrorType = 14

    julia> err.line
    1

    julia> err.column
    16

## Exporting data to TOML file

The `TOML.print` function is used to print (or serialize) data into TOML format.

    julia> using TOML

    julia> data = Dict(
              "names" => ["Julia", "Julio"],
              "age" => [10, 20],
           );

    julia> TOML.print(data)
    names = ["Julia", "Julio"]
    age = [10, 20]

    julia> fname = tempname();

    julia> open(fname, "w") do io
               TOML.print(io, data)
           end

    julia> TOML.parsefile(fname)
    Dict{String, Any} with 2 entries:
      "names" => ["Julia", "Julio"]
      "age"   => [10, 20]

Keys can be sorted according to some value

    julia> using TOML

    julia> TOML.print(Dict(
           "abc"  => 1,
           "ab"   => 2,
           "abcd" => 3,
           ); sorted=true, by=length)
    ab = 2
    abc = 1
    abcd = 3

For custom structs, pass a function that converts the struct to a supported type

    julia> using TOML

    julia> struct MyStruct
               a::Int
               b::String
           end

    julia> TOML.print(Dict("foo" => MyStruct(5, "bar"))) do x
               x isa MyStruct && return [x.a, x.b]
               error("unhandled type $(typeof(x))")
           end
    foo = [5, "bar"]

## Preserving comments

By default, comments in a TOML document are discarded when parsing, so writing the data out again loses them. To preserve comments, pass a `TOML.Comments` object to the parsing functions via the `comments` keyword argument and pass it back to `TOML.print`:

    julia> using TOML

    julia> comments = TOML.Comments();

    julia> data = TOML.parse("""
           # A comment attached to the entry below it
           name = "MyPkg"
           [compat]
           Dep = "~1.1" # an inline comment
           """; comments);

    julia> data["compat"]["OtherDep"] = "2";

    julia> TOML.print(data; comments, sorted=true)
    # A comment attached to the entry below it
    name = "MyPkg"

    [compat]
    Dep = "~1.1" # an inline comment
    OtherDep = "2"

Comments are associated with the items of the document (`key = value` entries and `[table]` headers) rather than with positions in the file, so the data can be freely modified and reformatted (e.g. with `sorted=true`) while the comments follow the items they belong to. The rules are:

- A block of whole-line comments with no blank line between the block and the following item is attached to that item, like a docstring, and is printed directly above it.

- A comment on the same line as an item is attached to that item and is printed on the same line, after the value.

- Any other whole-line comment (i.e. separated from the following item by a blank line, or at the end of a table or of the document) is floating: it is associated with the table it appears in and is printed at the top of that table, followed by a blank line.

- A comment attached (or associated) to an item that is deleted from the data is not printed; deleting an item deletes its comments.

- Comments inside a value that spans multiple lines (such as a multi-line array) are attached to the entry that owns the value and are printed above it.

- Comments on or inside the elements of an array of tables (`[[...]]`) are not preserved, except for a comment block attached to the first `[[...]]` header, which is printed above the first element. The key paths used to associate comments with items cannot distinguish between the elements of an array of tables.

Julia 1.14

Comment preservation requires Julia 1.14 or later.

## References

`TOML.parse` — Function

    parse(x::Union{AbstractString, IO}; comments=nothing)
    parse(p::Parser, x::Union{AbstractString, IO}; comments=nothing)

Parse the string or stream `x`, and return the resulting table (dictionary). Throw a `ParserError` upon failure.

If a `TOML.Comments` object is passed via the `comments` keyword argument, it is emptied and the comments of the document are captured into it.

Julia 1.14

The `comments` keyword argument requires Julia 1.14 or later.

See also `TOML.tryparse`.

source
`TOML.parsefile` — Function

    parsefile(f::AbstractString; comments=nothing)
    parsefile(p::Parser, f::AbstractString; comments=nothing)

Parse file `f` and return the resulting table (dictionary). Throw a `ParserError` upon failure.

If a `TOML.Comments` object is passed via the `comments` keyword argument, it is emptied and the comments of the document are captured into it.

Julia 1.14

The `comments` keyword argument requires Julia 1.14 or later.

See also `TOML.tryparsefile`.

source
`TOML.tryparse` — Function

    tryparse(x::Union{AbstractString, IO}; comments=nothing)
    tryparse(p::Parser, x::Union{AbstractString, IO}; comments=nothing)

Parse the string or stream `x`, and return the resulting table (dictionary). Return a `ParserError` upon failure.

If a `TOML.Comments` object is passed via the `comments` keyword argument, it is emptied and the comments of the document are captured into it.

Julia 1.14

The `comments` keyword argument requires Julia 1.14 or later.

See also `TOML.parse`.

source
`TOML.tryparsefile` — Function

    tryparsefile(f::AbstractString; comments=nothing)
    tryparsefile(p::Parser, f::AbstractString; comments=nothing)

Parse file `f` and return the resulting table (dictionary). Return a `ParserError` upon failure.

If a `TOML.Comments` object is passed via the `comments` keyword argument, it is emptied and the comments of the document are captured into it.

Julia 1.14

The `comments` keyword argument requires Julia 1.14 or later.

See also `TOML.parsefile`.

source
`TOML.print` — Function

    print([to_toml::Function], io::IO [=stdout], data::AbstractDict; sorted=false, by=identity, inline_tables::IdSet{<:AbstractDict}, comments=nothing)

Write `data` as TOML syntax to the stream `io`. If the keyword argument `sorted` is set to `true`, sort tables according to the function given by the keyword argument `by`. If the keyword argument `inline_tables` is given, it should be a set of tables that should be printed "inline".

If a `TOML.Comments` object (as populated by the parsing functions) is passed via the `comments` keyword argument, the comments in it are printed with the items they are associated with. Comments associated with items that are not present in `data` are ignored.

Julia 1.11

The `inline_tables` keyword argument is supported by Julia 1.11 or later.

Julia 1.14

The `comments` keyword argument requires Julia 1.14 or later.

The following data types are supported: `AbstractDict`, `AbstractVector`, `AbstractString`, `Integer`, `AbstractFloat`, `Bool`, `Dates.DateTime`, `Dates.Time`, `Dates.Date`. Note that the integers and floats need to be convertible to `Int64` and `Float64` respectively. For other data types, pass the function `to_toml` that takes the data types and returns a value of a supported type.

source
`TOML.Parser` — Type

    Parser()

Constructor for a TOML `Parser`. Note that in most cases one does not need to explicitly create a `Parser` but instead one directly uses `TOML.parsefile` or `TOML.parse`. Using an explicit parser will however reuse some internal data structures which can be beneficial for performance if a larger number of small files are parsed.

source
`TOML.ParserError` — Type

    ParserError

Type that is returned from `tryparse` and `tryparsefile` when parsing fails. It contains (among others) the following fields:

- `pos`, the position in the string when the error happened
- `table`, the result that so far was successfully parsed
- `type`, an error type, different for different types of errors

source
`TOML.Comments` — Type

    Comments()

A container for the comments of a TOML document. Pass an empty `Comments` object via the `comments` keyword argument of `TOML.parsefile`, `TOML.tryparsefile`, `TOML.parse` or `TOML.tryparse` to capture the comments of the parsed document into it, and pass it back via the `comments` keyword argument of `TOML.print` to write the comments out again. This allows modifying a TOML file without losing its comments:

    comments = TOML.Comments()
    data = TOML.parsefile("Project.toml"; comments)
    # ... modify data ...
    open("Project.toml", "w") do io
        TOML.print(io, data; comments)
    end

Comments are associated with the items of the document (see the TOML stdlib documentation for the precise rules): a block of whole-line comments directly above an item and a comment on the same line as an item are attached to that item and are printed with it (and dropped with it, if the item is removed from the data). Whole-line comments separated from the following item by a blank line are "floating": they are associated with the surrounding table and are printed at the top of it.

Julia 1.14

This type requires Julia 1.14 or later.

source

Theme

This document was generated with Documenter.jl version 1.17.0 on Saturday 29 August 2026. Using Julia version 1.14.0-DEV.3067.