---
title: "TOML"
lang: "en"
author: "Mohammad Abu Mattar"
canonical: https://mkabumattar.com/toml
---

[Home](/)›[Cheatsheets](/cheatsheets)

Cheatsheets

# TOML

TOML (Tom's Obvious, Minimal Language) is a configuration file format designed to be minimal, readable, and unambiguous. It's commonly used for application configuration, package manifests, and data serialization.

6 Categories18 Sections43 ExamplesPublished: 01 Aug 2023Updated: 28 Feb 2025

TOMLConfigurationData FormatTablesKeysValuesData TypesSyntax

[Markdown for AI(opens in a new tab)](/toml/index.md "Open the plain-Markdown version of this page, for pasting into an AI tool")

Series

[Config & Data Formats](/series/config--data-formats)5/5

[PreviousMarkdown](/cheatsheets/markdown)

All posts in this series (5)

Cheatsheets5

1.  [RegEx](/cheatsheets/regex)
2.  [YAML](/cheatsheets/yaml)
3.  [JSON](/cheatsheets/json)
4.  [Markdown](/cheatsheets/markdown)
5.  [TOMLYou are here](/cheatsheets/toml)

TOML (Tom’s Obvious, Minimal Language) is a human-friendly configuration file format. Designed to be minimal, readable, and unambiguous, it’s used extensively in package manifests (like Cargo.toml and pyproject.toml) and application configuration files.

Browse the sections below to explore TOML syntax, data types, and practical configuration examples.

[Getting Started](#category-getting-started)

-   [Basic Syntax](#section-basic-syntax)
-   [Data Types](#section-data-types)
-   [Key-Value Pairs](#section-key-value-pairs)

[Strings](#category-strings)

-   [Basic Strings](#section-basic-strings)
-   [Multiline Strings](#section-multiline-strings)
-   [String Escape Sequences](#section-string-escapes)

[Tables and Nesting](#category-tables-and-nesting)

-   [Basic Tables](#section-basic-tables)
-   [Array of Tables](#section-array-of-tables)
-   [Nested Structures](#section-nested-structures)

[Data Types](#category-data-types)

-   [Numbers](#section-numbers)
-   [Booleans and Null](#section-booleans-and-null)
-   [Dates and Times](#section-dates-and-times)

[Advanced Features](#category-advanced-features)

-   [Inline Tables](#section-inline-tables)
-   [Advanced DateTime](#section-datetime-advanced)
-   [Comments and Formatting](#section-comments-and-formatting)

[Best Practices](#category-best-practices)

-   [Common Patterns](#section-common-patterns)
-   [Readability and Style](#section-readability-and-style)
-   [Validation and Usage](#section-validation-and-usage)

No commands found

Try adjusting your search term

## Getting Started

Fundamental TOML concepts and syntax for beginners.

### Basic Syntax

Comments, whitespace, file format, and basic TOML structure.

#### Accessibility

Ensure comments and code blocks are clearly labeled for screen readers.

#### Best Practices

-   Use descriptive key names in lowercase with underscores.
-   Add comments to explain non-obvious configuration values.
-   Organize related configuration in sections.

#### Common Errors

-   **Spaces around the equals sign in key = value:** Keys and values must be separated by '=' with optional spaces: key = value is valid.
-   **Missing quotes on string values:** Use quotes for string values, e.g., title = "My App"

#### Keywords

syntaxcommentswhitespacetomlstructure

[Learn more](https://toml.io/en/v1.0.0)

#### Simple TOML file with comments

A basic TOML file demonstrating key-value pairs and comment usage.

Code

```
1# This is a comment2title = "My App"3
4# Comments can be placed anywhere5version = "1.0.0"
```

Execution

Terminal window

```
toml-parser config.toml
```

Output

Terminal window

```
title: "My App"version: "1.0.0"
```

-   Comments start with
-   Whitespace is ignored in most places.
-   Newlines separate key-value pairs.

#### Multi-line structure with sections

Demonstrates basic section structure and organization.

Code

```
1# Configuration file2name = "MyApp"3
4# Section for database5[database]6host = "localhost"7port = 5432
```

Execution

Terminal window

```
toml-parser config.toml
```

Output

Terminal window

```
name: "MyApp"database:  host: "localhost"  port: 5432
```

-   Sections are defined with \[section\_name\].
-   Keys within sections are nested under their section.

### Data Types

Overview of all TOML data types and their representations.

#### Accessibility

Clearly label each data type example for screen reader compatibility.

#### Best Practices

-   Use lowercase for keys and values when possible.
-   Be consistent with date and time formats (use ISO 8601).
-   Use descriptive names for array and table keys.

#### Common Errors

-   **Mixing data types in an array:** Arrays must contain values of the same type.

#### Keywords

data typesstringsnumbersbooleansarraystablesdatestoml

[Learn more](https://toml.io/en/v1.0.0#spec)

#### All primitive data types

Demonstrates each TOML primitive data type with examples.

Code

```
1# String2name = "Alice"3
4# Integer5count = 426
7# Float8pi = 3.141599
10# Boolean11enabled = true12
13# Date14birth = 1990-05-2715
16# Time17alarm = 15:30:0018
19# DateTime20created = 2021-12-25T10:30:00Z
```

Execution

Terminal window

```
toml-parser types.toml
```

Output

Terminal window

```
name: "Alice"count: 42pi: 3.14159enabled: truebirth: 1990-05-27alarm: 15:30:00created: 2021-12-25T10:30:00Z
```

-   TOML supports 7 data types: String, Integer, Float, Boolean, Date, Time, DateTime.
-   Type inference is automatic in TOML.

#### Arrays and tables

Shows how to define arrays, tables, and arrays of tables.

Code

```
1# Array2colors = ["red", "green", "blue"]3
4# Nested array5matrix = [[1, 2], [3, 4]]6
7# Table8[owner]9name = "Bob"10
11# Array of tables12[[products]]13id = 114name = "Widget"
```

Execution

Terminal window

```
toml-parser complex.toml
```

Output

Terminal window

```
colors: ["red", "green", "blue"]matrix: [[1, 2], [3, 4]]owner:  name: "Bob"products: [{ id: 1, name: "Widget" }]
```

-   Arrays are enclosed in brackets with comma-separated values.
-   Tables group related key-value pairs together.

### Key-Value Pairs

Syntax for defining keys and values in TOML documents.

#### Accessibility

Ensure all key naming examples are clearly labeled for screen readers.

#### Best Practices

-   Use lowercase, descriptive bare keys when possible.
-   Quote keys only when necessary for special characters.
-   Use dotted keys to organize related configuration.

#### Common Errors

-   **Unquoted key with spaces:** Quote keys that contain spaces, e.g., "my key" = value
-   **Duplicate key names:** Each key must be unique within its scope.

#### Keywords

keysvaluestomlassignmentnestingquoted keys

[Learn more](https://toml.io/en/v1.0.0#keys)

#### Simple key-value pairs

Demonstrates basic key-value pair syntax with different data types.

Code

```
1name = "Alice"2age = 303active = true4score = 92.5
```

Execution

Terminal window

```
toml-parser simple.toml
```

Output

Terminal window

```
name: "Alice"age: 30active: truescore: 92.5
```

-   Keys are case-sensitive.
-   Values must be separated from keys by an equals sign (=).

#### Quoted and dotted keys

Shows quoted keys and dotted key notation for nesting.

Code

```
1# Quoted key with spaces2"physical address" = "123 Main St"3
4# Single-quoted key5'special-key' = "value"6
7# Dotted key (nesting)8database.host = "localhost"9database.port = 543210database.credentials.user = "admin"
```

Execution

Terminal window

```
toml-parser keys.toml
```

Output

Terminal window

```
physical address: "123 Main St"special-key: "value"database:  host: "localhost"  port: 5432  credentials:    user: "admin"
```

-   Quoted keys can contain any character.
-   Dotted keys create nested tables automatically.
-   Keys must be unique within their scope.

#### Bare and quoted key combinations

Combines bare and quoted keys for flexibility in naming.

Code

```
1# Bare key (unquoted)2name = "Project"3
4# Keys with special characters must be quoted5"api-key" = "secret123"6"version 2.0" = true7
8# Mixed dotted keys9app.settings."user-preferences" = { theme = "dark" }
```

Execution

Terminal window

```
toml-parser mixed.toml
```

Output

Terminal window

```
name: "Project"api-key: "secret123"version 2.0: trueapp:  settings:    user-preferences:      theme: "dark"
```

-   Bare keys can only contain A-Z, a-z, 0-9, -, and \_.
-   Quote keys if they contain other characters.

## Strings

Working with string values in TOML documents.

### Basic Strings

Double-quoted strings with escape sequences and special characters.

#### Accessibility

Label escape sequences clearly for screen reader users.

#### Best Practices

-   Use escape sequences for special characters.
-   Keep strings readable by breaking long strings into multiple lines with multiline syntax.
-   Use raw strings for paths containing backslashes.

#### Common Errors

-   **Unescaped quotes inside strings:** Escape quotes with backslash, e.g., \\"
-   **Literal backslashes not escaped:** Double the backslash, e.g., \\\\ for a single backslash

#### Keywords

stringsquotesescape sequencestoml

[Learn more](https://toml.io/en/v1.0.0#string)

#### Simple string values

Basic string values enclosed in double quotes.

Code

```
1title = "Hello World"2description = "A simple configuration file"3path = "C:\\Users\\Alice\\Documents"
```

Execution

Terminal window

```
toml-parser strings.toml
```

Output

Terminal window

```
title: "Hello World"description: "A simple configuration file"path: "C:\\Users\\Alice\\Documents"
```

-   Strings are enclosed in double quotes.
-   Backslashes can be included by escaping them.

#### Escaped characters

Various escape sequences used in TOML strings.

Code

```
1# Common escape sequences2tab = "Column1\tColumn2"3newline = "Line1\nLine2"4quote = "She said \"Hello!\""5backslash = "C:\\path\\to\\file"6unicode = "Café: \u00e9"
```

Execution

Terminal window

```
toml-parser escaped.toml
```

Output

Terminal window

```
tab: "Column1  Column2"newline: "Line1\nLine2"quote: "She said \"Hello!\""backslash: "C:\path\to\file"unicode: "Café: é"
```

-   Use \\t for tabs, \\n for newlines, \\" for quotes.
-   Use \\u for 4-digit Unicode escapes, \\U for 8-digit.

### Multiline Strings

Triple-quoted strings for multi-line content with literal or folded modes.

#### Accessibility

Clearly indicate line breaks in multiline string examples.

#### Best Practices

-   Use multiline strings for long descriptions or formatted text.
-   Use literal multiline strings for paths or code snippets.
-   Use line folding to keep long strings readable without breaking them.

#### Common Errors

-   **Trying to escape characters in literal strings:** Literal strings don't support escaping; use basic strings if needed.

#### Keywords

multilinestringstriple quotestomlfolding

[Learn more](https://toml.io/en/v1.0.0#string)

#### Multiline basic string

A basic multiline string using triple double quotes.

Code

```
1description = """2This is a multiline3string with multiple4lines of text."""
```

Execution

Terminal window

```
toml-parser multiline.toml
```

Output

Terminal window

```
description: "This is a multiline\nstring with multiple\nlines of text."
```

-   Multiline strings preserve newlines.
-   The first newline after the opening quotes is trimmed.
-   Escape sequences still work in multiline strings.

#### Multiline literal string

Literal multiline strings preserve content exactly, no escaping needed.

Code

```
1path = '''2C:\Users\Alice3C:\Users\Bob4'''
```

Execution

Terminal window

```
toml-parser literal.toml
```

Output

Terminal window

```
path: "C:\Users\Alice\nC:\Users\Bob"
```

-   Literal strings use triple single quotes.
-   No escape sequences are processed in literal strings.
-   Useful for paths, JSON, or other literal content.

#### Line folding in multiline strings

Using backslash to fold long lines without adding newlines.

Code

```
1text = """2This is a long line \3that continues \4on the next line."""
```

Execution

Terminal window

```
toml-parser fold.toml
```

Output

Terminal window

```
text: "This is a long line that continues on the next line."
```

-   A backslash at the end of a line continues to the next without adding a newline.
-   This helps keep long strings readable.

### String Escape Sequences

All available escape sequences in TOML strings.

#### Accessibility

Provide clear descriptions of what each escape sequence produces.

#### Best Practices

-   Use \\n for line breaks instead of literal newlines when readability is important.
-   Use \\u and \\U for characters not easily typed on your keyboard.
-   Keep escape sequences simple; use literal strings when possible.

#### Common Errors

-   **Using wrong escape sequence:** Use the correct sequence (e.g., \\n for newline, not \\l).
-   **Invalid Unicode code point:** Verify the Unicode value is within the valid range.

#### Keywords

escapesstringsunicodespecial characterstoml

[Learn more](https://toml.io/en/v1.0.0#string)

#### Common escape sequences

Standard escape sequences for control and special characters.

Code

```
1backspace = "Back\bspace"2tab = "Tab\there"3linefeed = "Line\nfeed"4form_feed = "Form\ffeed"5carriage_return = "Return\rhere"6quote = "Quote: \"Hello\""7backslash = "Backslash: \\"
```

Execution

Terminal window

```
toml-parser escapes.toml
```

Output

Terminal window

```
backspace: "Back\bspace"tab: "Tab  here"linefeed: "Line\nfeed"form_feed: "Form\ffeed"carriage_return: "Return\rhere"quote: "Quote: \"Hello\""backslash: "Backslash: \"
```

-   \\b = backspace (U+0008)
-   \\t = tab (U+0009)
-   \\n = line feed (U+000A)
-   \\f = form feed (U+000C)
-   \\r = carriage return (U+000D)
-   \\" = quotation mark (U+0022)
-   \\\\ = backslash (U+005C)

#### Unicode escape sequences

Unicode escapes for 4-digit and 8-digit code points.

Code

```
1# 4-digit Unicode escape2emoji = "Smile: \u263A"3
4# 8-digit Unicode escape5complex = "Mathematical: \U0001D400"6
7# Mix with characters8text = "Greek: \u03B1\u03B2\u03B3"
```

Execution

Terminal window

```
toml-parser unicode.toml
```

Output

Terminal window

```
emoji: "Smile: ☺"complex: "Mathematical: 𝐀"text: "Greek: αβγ"
```

-   \\uXXXX for 4-digit Unicode escapes (U+0000 to U+FFFF)
-   \\UXXXXXXXX for 8-digit Unicode escapes (U+00000000 to U+7FFFFFFF)
-   Use for emoji and special characters not easily typed.

## Tables and Nesting

Defining and organizing tables in TOML documents.

### Basic Tables

Simple table headers, dot-separated keys, and subtables.

#### Accessibility

Clearly label table sections and nesting hierarchy.

#### Best Practices

-   Use descriptive table names in lowercase.
-   Group related configuration into tables.
-   Use dot notation for simple nested values, explicit headers for complex sections.

#### Common Errors

-   **Redefining a table header:** Define each table only once; use dotted keys if you need to add more values later.
-   **Mixing key and table for the same name:** A name cannot be both a key and a table header in the same scope.

#### Keywords

tablesheadersnestingsectionstoml

[Learn more](https://toml.io/en/v1.0.0#table)

#### Simple table definition

Defines two tables with their respective key-value pairs.

Code

```
1[owner]2name = "Alice"3email = "alice@example.com"4
5[database]6host = "localhost"7port = 5432
```

Execution

Terminal window

```
toml-parser tables.toml
```

Output

Terminal window

```
owner:  name: "Alice"  email: "alice@example.com"database:  host: "localhost"  port: 5432
```

-   Tables are headers enclosed in brackets \[table\_name\].
-   Keys after a table belong to that table.
-   Whitespace in table names is allowed only in quoted names.

#### Nested tables with dot notation

Shows both dot notation and explicit table headers for nesting.

Code

```
1# Using dot notation for subtables2database.connection.host = "localhost"3database.connection.port = 54324database.connection.ssl = true5
6[database.credentials]7user = "admin"8password = "secret"
```

Execution

Terminal window

```
toml-parser nested.toml
```

Output

Terminal window

```
database:  connection:    host: "localhost"    port: 5432    ssl: true  credentials:    user: "admin"    password: "secret"
```

-   Dotted keys create nested tables automatically.
-   Can mix dotted keys with explicit table headers.
-   Parent tables are created automatically if needed.

#### Nested subtables

Hierarchical nesting of tables using bracket notation.

Code

```
1[server]2host = "0.0.0.0"3port = 80804
5[server.ssl]6enabled = true7cert = "/path/to/cert"8
9[server.ssl.options]10min_version = "TLSv1.2"
```

Execution

Terminal window

```
toml-parser subtables.toml
```

Output

Terminal window

```
server:  host: "0.0.0.0"  port: 8080  ssl:    enabled: true    cert: "/path/to/cert"    options:      min_version: "TLSv1.2"
```

-   \[parent.child\] defines subtables of parent.
-   Each table must be defined only once (no redefinition).

### Array of Tables

Using \[\[array.of.tables\]\] syntax for multiple table items.

#### Accessibility

Clearly indicate array structure and iteration.

#### Best Practices

-   Use array of tables for lists of similar items.
-   Keep table items small and focused.
-   Use descriptive key names within each table element.

#### Common Errors

-   **Inconsistent structure in array elements:** All elements in an array should have the same structure.
-   **Missing \[\[brackets\]\] for array items:** Use \[\[name\]\] for arrays, not just \[name\].

#### Keywords

arraystablesmultiple itemstomlbrackets

[Learn more](https://toml.io/en/v1.0.0#array-of-tables)

#### Simple array of tables

Creates an array of table elements with multiple items.

Code

```
1[[products]]2id = 13name = "Widget"4price = 9.995
6[[products]]7id = 28name = "Gadget"9price = 19.99
```

Execution

Terminal window

```
toml-parser array_tables.toml
```

Output

Terminal window

```
products:  - id: 1    name: "Widget"    price: 9.99  - id: 2    name: "Gadget"    price: 19.99
```

-   \[\[table\_name\]\] appends a new table to an array.
-   Each \[\[table\_name\]\] block creates a new element.
-   All elements have the same structure.

#### Nested array of tables

Array of tables nested within a parent table.

Code

```
1[package]2name = "my-package"3
4[[package.dependencies]]5name = "requests"6version = "2.28.0"7
8[[package.dependencies]]9name = "flask"10version = "2.0.0"
```

Execution

Terminal window

```
toml-parser nested_array.toml
```

Output

Terminal window

```
package:  name: "my-package"  dependencies:    - name: "requests"      version: "2.28.0"    - name: "flask"      version: "2.0.0"
```

-   \[\[parent.child\]\] creates an array within the parent table.
-   Each child table is a separate element in the array.

#### Multiple arrays of tables

Multiple independent arrays of tables in the same document.

Code

```
1[[users]]2name = "Alice"3role = "admin"4
5[[users]]6name = "Bob"7role = "user"8
9[[projects]]10title = "Project A"11owner = "Alice"12
13[[projects]]14title = "Project B"15owner = "Bob"
```

Execution

Terminal window

```
toml-parser multiple_arrays.toml
```

Output

Terminal window

```
users:  - name: "Alice"    role: "admin"  - name: "Bob"    role: "user"projects:  - title: "Project A"    owner: "Alice"  - title: "Project B"    owner: "Bob"
```

-   Each \[\[name\]\] creates a separate array.
-   Arrays can be defined independently.

### Nested Structures

Complex deeply nested tables and hierarchical data.

#### Accessibility

Use clear indentation and labeling for complex nesting.

#### Best Practices

-   Keep nesting to reasonable depth (3-4 levels typically).
-   Use clear, intuitive naming for parent tables.
-   Document complex structures with comments.

#### Common Errors

-   **Overly deep nesting causing readability issues:** Consider flattening some levels or using dotted keys.
-   **Forgetting parent table context in arrays:** Use \[\[parent.child\]\] syntax correctly.

#### Keywords

nestedhierarchicalcomplexdeep nestingtoml

[Learn more](https://toml.io/en/v1.0.0#table)

#### Deeply nested tables

Demonstrates multiple levels of nesting with different branches.

Code

```
1[server.http.handlers.api]2endpoint = "/api/v1"3timeout = 304
5[server.http.handlers.websocket]6endpoint = "/ws"7timeout = 08
9[server.https.ssl]10cert = "/path/to/cert"11key = "/path/to/key"
```

Execution

Terminal window

```
toml-parser deep_nesting.toml
```

Output

Terminal window

```
server:  http:    handlers:      api:        endpoint: "/api/v1"        timeout: 30      websocket:        endpoint: "/ws"        timeout: 0  https:    ssl:      cert: "/path/to/cert"      key: "/path/to/key"
```

-   TOML supports unlimited nesting depth.
-   Use clear naming to avoid confusion in deeply nested structures.
-   Dotted keys can simplify defining deeply nested values.

#### Complex hierarchical structure

Combines tables, arrays of tables, and nested structures.

Code

```
1[app]2name = "MyApp"3version = "1.0.0"4
5[app.features]6auth = true7api = true8websocket = false9
10[[app.features.modules]]11name = "Auth"12enabled = true13
14[[app.features.modules]]15name = "API"16enabled = true17
18[app.logging]19level = "info"20format = "json"
```

Execution

Terminal window

```
toml-parser complex_nested.toml
```

Output

Terminal window

```
app:  name: "MyApp"  version: "1.0.0"  features:    auth: true    api: true    websocket: false    modules:      - name: "Auth"        enabled: true      - name: "API"        enabled: true  logging:    level: "info"    format: "json"
```

-   Mix different structure types for flexibility.
-   Organize by functionality or domain.

## Data Types

Detailed coverage of TOML data types and representations.

### Numbers

Integers, floats, scientific notation, and underscores in numbers.

#### Accessibility

Clearly label different number formats and their values.

#### Best Practices

-   Use underscores in large numbers for readability.
-   Be consistent with notation (all hex, all decimal, etc.).
-   Use scientific notation for very large or small values.

#### Common Errors

-   **Leading zeros in decimal integers:** Use hex/octal/binary notation for numbers with prefixes.
-   **Underscores at start or end of number:** Underscores can only appear between digits.

#### Keywords

numbersintegersfloatsscientific notationunderscoretoml

[Learn more](https://toml.io/en/v1.0.0#integer)

#### Integer number formats

TOML supports decimal, hexadecimal, octal, and binary integers.

Code

```
1# Decimal integers2count = 423negative = -174
5# Hexadecimal (0x prefix)6hex_value = 0xDEADBEEF7
8# Octal (0o prefix)9octal = 0o75510
11# Binary (0b prefix)12binary = 0b11010110
```

Execution

Terminal window

```
toml-parser integers.toml
```

Output

Terminal window

```
count: 42negative: -17hex_value: 3735928559octal: 493binary: 214
```

-   Integers are 64-bit signed numbers.
-   Leading zeros are not allowed in decimal notation.
-   Hex, octal, and binary integers have specific prefixes.

#### Float number formats

TOML supports standard floats, scientific notation, and special values.

Code

```
1# Standard float2pi = 3.141593
4# Negative float5temperature = -40.06
7# Scientific notation8large = 5e+229small = 1.47e-1210
11# Special float values12infinity = inf13neg_infinity = -inf14not_number = nan
```

Execution

Terminal window

```
toml-parser floats.toml
```

Output

Terminal window

```
pi: 3.14159temperature: -40.0large: 5e+22small: 1.47e-12infinity: Infinityneg_infinity: -Infinitynot_number: NaN
```

-   Floats are 64-bit (IEEE 754 double precision).
-   Scientific notation uses 'e' or 'E'.
-   Special values inf, -inf, nan represent infinity and NaN.

#### Numbers with underscores

Underscores improve readability of large numbers.

Code

```
1# Readable large numbers2million = 1_000_0003phone = 555_123_45674binary = 0b1010_10105
6# Floats with underscores7pi = 3.14_159_2658scientific = 1.602_176_634e-19
```

Execution

Terminal window

```
toml-parser underscores.toml
```

Output

Terminal window

```
million: 1000000phone: 5551234567binary: 170pi: 3.14159265scientific: 1.602176634e-19
```

-   Underscores can be placed between digits for readability.
-   Leading/trailing underscores are not allowed.
-   Underscores are ignored during parsing.

### Booleans and Null

Boolean true/false values and null representation in TOML.

#### Accessibility

Clearly distinguish between true and false values.

#### Best Practices

-   Use boolean values for on/off or enabled/disabled settings.
-   Omit optional keys rather than using null-like values.
-   Document how absence is represented in your TOML files.

#### Common Errors

-   **Using True or False (capitalized):** Use lowercase true and false.
-   **Trying to use null or None:** TOML doesn't support null; omit the key or use "null" string.

#### Advanced Notes

-   **Handling Optional Values:** Consider using a separate section to list which keys are optional.

#### Keywords

booleanstruetoml

[Learn more](https://toml.io/en/v1.0.0#boolean)

#### Boolean values

TOML uses lowercase true and false for boolean values.

Code

```
1# Boolean values are lowercase2enabled = true3debug = false4
5[features]6auth = true7logging = false8updates = true
```

Execution

Terminal window

```
toml-parser booleans.toml
```

Output

Terminal window

```
enabled: truedebug: falsefeatures:  auth: true  logging: false  updates: true
```

-   Boolean values are lowercase (true, false).
-   No yes/no or on/off alternatives in TOML.
-   Booleans are distinct from strings.

#### Representing null or absence

TOML doesn't have a null type; use conventions or omit keys.

Code

```
1# TOML doesn't have a native null type2# Options for representing absence:3
4# 1. Omit the key entirely5# optional_field = (not present)6
7# 2. Use empty string8empty = ""9
10# 3. Use special marker values11null_marker = "null"12unset = "unset"13none = "none"
```

Execution

Terminal window

```
toml-parser null.toml
```

Output

Terminal window

```
empty: ""null_marker: "null"unset: "unset"none: "none"
```

-   TOML does not have a native null or None value.
-   Omit the key entirely to represent absence.
-   Use empty string or special marker strings if needed.

### Dates and Times

ISO 8601 formatted dates, times, and datetimes with timezone support.

#### Accessibility

Provide clear examples of date/time formats with explanations.

#### Best Practices

-   Use ISO 8601 format consistently throughout your TOML files.
-   Use Z for UTC times; include offset for other timezones.
-   Include timezone information for important timestamps.

#### Common Errors

-   **Using non-ISO 8601 date formats:** Always use YYYY-MM-DD format for dates.
-   **Missing timezone information in datetimes:** Add Z for UTC or ±HH:MM for other timezones.

#### Advanced Notes

-   **Time Precision:** Fractional seconds can include up to nanosecond precision (9 digits).

#### Keywords

datestimesdatetimeISO 8601timezonetoml

[Learn more](https://toml.io/en/v1.0.0#offset-date-time)

#### Date and time formats

Basic date, time, and local datetime formats in ISO 8601.

Code

```
1# Date (RFC 3339 profile of ISO 8601)2birthday = 1990-05-273
4# Time (no date)5alarm = 15:30:006
7# Local DateTime (date and time, no timezone)8meeting = 2021-12-25T10:30:00
```

Execution

Terminal window

```
toml-parser dates.toml
```

Output

Terminal window

```
birthday: 1990-05-27alarm: 15:30:00meeting: 2021-12-25T10:30:00
```

-   Dates follow YYYY-MM-DD format.
-   Times follow HH:MM:SS or HH:MM:SS.ffffff format.
-   LocalDateTime combines date and time without timezone.

#### Datetime with timezone

Datetime values with timezone information and fractional seconds.

Code

```
1# UTC timezone (Z suffix)2created = 2021-12-25T10:30:00Z3
4# With offset5eastern = 2021-12-25T10:30:00-05:006
7# With positive offset8tokyo = 2021-12-25T10:30:00+09:009
10# Milliseconds precision11precise = 2021-12-25T10:30:00.123Z
```

Execution

Terminal window

```
toml-parser datetimes.toml
```

Output

Terminal window

```
created: 2021-12-25T10:30:00Zeastern: 2021-12-25T10:30:00-05:00tokyo: 2021-12-25T10:30:00+09:00precise: 2021-12-25T10:30:00.123Z
```

-   Z suffix indicates UTC (Zulu) time.
-   Offset format is ±HH:MM.
-   Fractional seconds support up to nanosecond precision.

## Advanced Features

Advanced TOML features for complex configurations.

### Inline Tables

Compact single-line table syntax with {key = value} format.

#### Accessibility

Clearly show how inline tables are structured and parsed.

#### Best Practices

-   Use inline tables for simple, fixed structures.
-   Keep inline tables concise and readable.
-   Use regular tables for complex or frequently updated structures.

#### Common Errors

-   **Trying to extend an inline table:** Inline tables are immutable and cannot be modified later.
-   **Multi-line inline table:** Inline tables must be on a single line.

#### Keywords

inlinetablescompactsingle-linetoml

[Learn more](https://toml.io/en/v1.0.0#inline-table)

#### Simple inline table

Inline tables provide a compact way to define tables on a single line.

Code

```
1point = { x = 1, y = 2 }2color = { r = 255, g = 128, b = 0 }3person = { name = "Alice", age = 30 }
```

Execution

Terminal window

```
toml-parser inline.toml
```

Output

Terminal window

```
point:  x: 1  y: 2color:  r: 255  g: 128  b: 0person:  name: "Alice"  age: 30
```

-   Inline tables are enclosed in curly braces.
-   Keys and values are separated by equals with optional spaces.
-   Inline tables cannot span multiple lines.

#### Nested inline tables

Inline tables can be nested and used in arrays.

Code

```
1# Inline table containing inline table2config = {3  database = { host = "localhost", port = 5432 },4  cache = { host = "redis", ttl = 3600 }5}6
7# Array of inline tables8points = [9  { x = 0, y = 0 },10  { x = 1, y = 2 },11  { x = 3, y = 4 }12]
```

Execution

Terminal window

```
toml-parser nested_inline.toml
```

Output

Terminal window

```
config:  database:    host: "localhost"    port: 5432  cache:    host: "redis"    ttl: 3600points:  - x: 0    y: 0  - x: 1    y: 2  - x: 3    y: 4
```

-   Inline tables cannot be redefined or extended later.
-   Useful for simple, fixed data structures.

### Advanced DateTime

Offset datetimes, local datetimes, and time precision handling.

#### Accessibility

Show various datetime formats with clear labels.

#### Best Practices

-   Use UTC time (Z) for server logs and critical timestamps.
-   Include timezone offset for user-facing timestamps.
-   Use local datetime for scheduling without timezone sensitivity.

#### Common Errors

-   **Invalid timezone offset format:** Use ±HH:MM format, e.g., -05:00, not -5:00 or -0500.
-   **Missing fractional seconds in precise times:** Include fractional seconds if they're important for your use case.

#### Keywords

datetimetimezoneoffsetprecisionlocaltoml

[Learn more](https://toml.io/en/v1.0.0#offset-date-time)

#### All datetime variants

Examples of all TOML datetime type variants.

Code

```
1# Offset DateTime (with timezone)2utc_time = 2021-12-25T10:30:00Z3eastern_time = 2021-12-25T10:30:00-05:004
5# Local DateTime (no timezone)6local_meeting = 2021-12-25T10:30:007
8# Local Date (no time)9deadline = 2021-12-3110
11# Local Time (no date)12opening_time = 09:00:00
```

Execution

Terminal window

```
toml-parser all_datetime.toml
```

Output

Terminal window

```
utc_time: 2021-12-25T10:30:00Zeastern_time: 2021-12-25T10:30:00-05:00local_meeting: 2021-12-25T10:30:00deadline: 2021-12-31opening_time: 09:00:00
```

-   Offset DateTime includes timezone information.
-   Local DateTime is timezone-naive.
-   Local Date and Local Time can exist independently.

#### Fractional seconds and precision

Demonstrates various precision levels in fractional seconds.

Code

```
1# Milliseconds2ms_precision = 2021-12-25T10:30:00.123Z3
4# Microseconds5us_precision = 2021-12-25T10:30:00.123456Z6
7# Nanoseconds8ns_precision = 2021-12-25T10:30:00.123456789Z9
10# Trailing zeros11long_precision = 2021-12-25T10:30:00.1Z
```

Execution

Terminal window

```
toml-parser precision.toml
```

Output

Terminal window

```
ms_precision: 2021-12-25T10:30:00.123Zus_precision: 2021-12-25T10:30:00.123456Zns_precision: 2021-12-25T10:30:00.123456789Zlong_precision: 2021-12-25T10:30:00.1Z
```

-   Fractional seconds are optional and can be 1-9 digits.
-   No precision loss; values are preserved as specified.

### Comments and Formatting

Effective commenting and formatting practices in TOML.

#### Accessibility

Ensure comments are clear and organized for all readers.

#### Best Practices

-   Start files with a header comment explaining the purpose.
-   Add inline comments for non-obvious values.
-   Use visual separators between major sections.
-   Keep comments current with the configuration.

#### Common Errors

-   **Over-commenting obvious values:** Comment only when the purpose isn't clear from the key name.
-   **Outdated comments that don't match the configuration:** Update comments when configuration changes.

#### Keywords

commentsformattingstylereadabilityorganizationtoml

[Learn more](https://toml.io/en/v1.0.0#comment)

#### Effective commenting

Shows effective use of comments for documentation.

Code

```
1# Main application configuration2# Last updated: 2025-02-283
4title = "MyApp"  # Application title5version = "1.0.0"6
7# Database connection settings8[database]9host = "localhost"  # Database server hostname10port = 5432         # Standard PostgreSQL port11ssl = true          # Enable SSL for secure connections
```

Execution

Terminal window

```
toml-parser commented.toml
```

Output

Terminal window

```
title: "MyApp"version: "1.0.0"database:  host: "localhost"  port: 5432  ssl: true
```

-   Comments start with
-   Inline comments are allowed after values.
-   Comments help clarify non-obvious configuration.

#### Organized file structure

Well-organized file structure with clear section headers.

Code

```
1# ============================================================================2# Application Configuration3# ============================================================================4
5[metadata]6name = "MyApp"7version = "1.0.0"8author = "Team"9
10# ============================================================================11# Server Configuration12# ============================================================================13
14[server]15host = "0.0.0.0"16port = 808017
18[server.ssl]19enabled = true20cert = "/path/to/cert"21
22# ============================================================================23# Database Configuration24# ============================================================================25
26[database]27url = "postgresql://localhost/mydb"
```

Execution

Terminal window

```
toml-parser organized.toml
```

Output

Terminal window

```
metadata:  name: "MyApp"  version: "1.0.0"  author: "Team"server:  host: "0.0.0.0"  port: 8080  ssl:    enabled: true    cert: "/path/to/cert"database:  url: "postgresql://localhost/mydb"
```

-   Use visual separators (comment lines) for clarity.
-   Group related configurations into sections.
-   Maintain consistent formatting throughout the file.

## Best Practices

Best practices for writing effective TOML configurations.

### Common Patterns

Patterns used in real-world TOML files and package manifests.

#### Accessibility

Provide clear examples of real-world patterns.

#### Best Practices

-   Follow established patterns for your project type.
-   Use consistent naming conventions throughout.
-   Group related settings into sections.
-   Include version and author information where appropriate.

#### Common Errors

-   **Inventing custom patterns instead of following standards:** Follow established patterns for Cargo.toml, pyproject.toml, etc.
-   **Inconsistent key naming across configuration:** Establish and follow a naming convention consistently.

#### Keywords

patternscargopyprojectconfigstandardsexamplestoml

[Learn more](https://toml.io/en/v1.0.0)

#### Cargo.toml (Rust) style

Standard structure of Cargo.toml for Rust projects.

Code

```
1[package]2name = "my-app"3version = "0.1.0"4edition = "2021"5description = "My awesome application"6authors = ["Me <me@example.com>"]7
8[dependencies]9serde = { version = "1.0", features = ["derive"] }10tokio = { version = "1.0", features = ["full"] }11
12[dev-dependencies]13pytest = "0.13"14
15[profile.release]16opt-level = 3
```

Execution

Terminal window

```
cargo build
```

-   \[package\] section contains metadata.
-   \[dependencies\] lists production dependencies.
-   \[dev-dependencies\] for testing dependencies.
-   Feature specifications are common.

#### pyproject.toml (Python) style

Standard structure of pyproject.toml for Python projects.

Code

```
1[project]2name = "my-package"3version = "0.1.0"4description = "A Python package"5authors = [{name = "Alice", email = "alice@example.com"}]6requires-python = ">=3.8"7
8[project.dependencies]9requests = ">=2.0"10flask = ">=2.0"11
12[build-system]13requires = ["setuptools", "wheel"]14build-backend = "setuptools.build_meta"
```

Execution

Terminal window

```
pip install .
```

-   \[project\] contains package metadata.
-   Author details use inline table format.
-   \[build-system\] specifies build requirements.

#### Application config file pattern

Typical application configuration file structure.

Code

```
1# [app.toml] - Server configuration2[app]3name = "MyService"4environment = "production"5debug = false6
7[server]8host = "0.0.0.0"9port = 808010workers = 411
12[database]13url = "postgresql://user:pass@localhost/db"14pool_size = 2015
16[logging]17level = "info"18format = "json"19file = "/var/log/myservice.log"20
21[[services]]22name = "auth"23url = "http://auth-service:8000"24
25[[services]]26name = "cache"27url = "redis://localhost:6379"
```

Execution

Terminal window

```
myapp --config app.toml
```

-   Metadata in \[app\] section.
-   Server/database settings in dedicated sections.
-   External services in array of tables.

### Readability and Style

Organizing keys and maintaining consistent formatting.

#### Accessibility

Demonstrate clear, readable configuration organization.

#### Best Practices

-   Use snake\_case for all keys.
-   Group related settings under the same table.
-   Add section comments explaining purpose.
-   Order sections logically (metadata, core settings, optional).

#### Common Errors

-   **Inconsistent key naming (camelCase vs snake\_case):** Use snake\_case consistently throughout.
-   **Poor organization making files hard to navigate:** Group related settings and add comments.

#### Advanced Notes

-   **Configuration Validation:** Consider tools that validate TOML structure against a schema.

#### Keywords

readabilitystyleorganizationformattingnamingconventionstoml

[Learn more](https://toml.io/en/v1.0.0)

#### Well-organized TOML file

Configuration organized for clarity and maintainability.

Code

```
1# Services Configuration2# Well-organized with logical grouping3
4[metadata]5version = "1.0.0"6updated = 2025-02-287
8[api]9# Core API settings10host = "0.0.0.0"11port = 800012timeout = 3013
14[api.auth]15# Authentication configuration16enabled = true17jwt_secret = "your-secret-key"18token_expire_hours = 2419
20[api.cors]21# CORS settings22allowed_origins = ["http://localhost:3000"]23allowed_methods = ["GET", "POST", "PUT"]24
25[database]26host = "localhost"27port = 543228name = "myapp"29pool_size = 2030
31[logging]32level = "info"33format = "json"
```

Execution

Terminal window

```
app --config config.toml
```

-   Use descriptive section names.
-   Add comments explaining purpose of sections.
-   Keep related items grouped together.
-   Use consistent indentation (though not required).

#### Naming conventions

Demonstrates consistent naming conventions.

Code

```
1# ✓ Good naming conventions2[database]3connection_timeout = 104max_pool_size = 205retry_attempts = 36
7[cache]8redis_host = "localhost"9redis_port = 637910ttl_seconds = 360011
12[service]13api_key = "secret"14api_version = "v1"15api_timeout = 30
```

Execution

Terminal window

```
app --validate-config
```

Output

Terminal window

```
Configuration is valid
```

-   Use snake\_case for key names.
-   Use descriptive suffixes (\_host, \_port, \_timeout, etc.).
-   Keep names consistent across similar settings.
-   Avoid ambiguous abbreviations.

### Validation and Usage

Loading and parsing TOML files in programming languages.

#### Accessibility

Provide clear code examples in different languages.

#### Best Practices

-   Use language-native libraries when possible.
-   Validate TOML structure against a schema.
-   Provide default values for optional configuration.
-   Handle missing configuration files gracefully.

#### Common Errors

-   **Assuming all TOML parsers handle all types:** Check library documentation for type support.
-   **Not validating parsed configuration:** Validate required fields and types after loading.

#### Advanced Notes

-   **Configuration Merging:** Consider merging multiple TOML files for environment-specific configs.
-   **Hot Reloading:** Some applications support reloading config without restart.

#### Keywords

parsingloadingvalidationlibrariesexampleslanguagestoml

[Learn more](https://toml.io/en/v1.0.0/spec.txt)

#### Python - Loading TOML with tomllib

Python example using the built-in tomllib module (Python 3.11+).

Code

```
1[app]2name = "MyApp"3debug = false4
5[database]6url = "postgresql://localhost/myapp"7pool_size = 20
```

Execution

```
1import tomllib2
3with open('config.toml', 'rb') as f:4    config = tomllib.load(f)5
6print(config['app']['name'])7print(config['database']['pool_size'])
```

Output

Terminal window

```
MyApp20
```

-   tomllib requires opened file in binary mode ('rb').
-   For older Python, use the 'tomli' package.
-   Returns a dictionary with nested structure.

#### Rust - Loading TOML with toml crate

Rust uses the toml crate to parse TOML files.

Code

```
1[server]2host = "0.0.0.0"3port = 80804
5[server.ssl]6cert = "/path/to/cert.pem"7key = "/path/to/key.pem"
```

Execution

Terminal window

```
cargo run
```

Output

Terminal window

```
Server listening on 0.0.0.0:8080
```

-   Rust has strong typing for TOML values.
-   Use serde for deserializing into structs.
-   Includes validation through type checking.

#### TOML validation and schema

Validation checks that TOML matches the expected structure.

Code

```
1# Configuration that should be validated2[app]3name = "Service"4
5# Required fields: app.name, server.port6# Optional fields: debug, logging.level7
8[server]9port = 808010# host must be an IP or hostname11host = "0.0.0.0"12
13[logging]14level = "info"  # must be: debug, info, warn, error
```

Execution

Terminal window

```
validate-toml --schema config.schema.json config.toml
```

Output

Terminal window

```
Configuration is valid
```

-   JSON Schema can define TOML structure.
-   Type checking during deserialization.
-   Document required vs optional fields.

Was this useful?

## Tags

#TOML#Configuration#Data Format#Tables#Keys#Values#Data Types#Syntax

## Share

[Facebook](https://facebook.com/sharer/sharer.php?u=https%3A%2F%2Fmkabumattar.com%2Fcheatsheets%2Ftoml "Share on Facebook")[Twitter](https://twitter.com/intent/tweet/?text=TOML&url=https%3A%2F%2Fmkabumattar.com%2Fcheatsheets%2Ftoml "Share on Twitter")[LinkedIn](https://www.linkedin.com/shareArticle?mini=true&url=https%3A%2F%2Fmkabumattar.com%2Fcheatsheets%2Ftoml&title=TOML&summary=TOML%20\(Tom's%20Obvious%2C%20Minimal%20Language\)%20is%20a%20configuration%20file%20format%20designed%20to%20be%20minimal%2C%20readable%2C%20and%20unambiguous.%20It's%20commonly%20used%20for%20application%20configuration%2C%20package%20manifests%2C%20and%20data%20serialization.&source=https://mkabumattar.com "Share on LinkedIn")[WhatsApp](https://wa.me/?text=TOML%20https%3A%2F%2Fmkabumattar.com%2Fcheatsheets%2Ftoml "Share on WhatsApp")[Telegram](https://t.me/share/url?url=https%3A%2F%2Fmkabumattar.com%2Fcheatsheets%2Ftoml&text=TOML "Share on Telegram")[Reddit](https://www.reddit.com/submit?url=https%3A%2F%2Fmkabumattar.com%2Fcheatsheets%2Ftoml&title=TOML "Share on Reddit")[Hacker News](http://news.ycombinator.com/submitlink?u=https%3A%2F%2Fmkabumattar.com%2Fcheatsheets%2Ftoml&t=TOML "Share on Hacker News")[Pinterest](https://pinterest.com/pin/create/button/?url=https%3A%2F%2Fmkabumattar.com%2Fcheatsheets%2Ftoml&media=&description=TOML%20\(Tom's%20Obvious%2C%20Minimal%20Language\)%20is%20a%20configuration%20file%20format%20designed%20to%20be%20minimal%2C%20readable%2C%20and%20unambiguous.%20It's%20commonly%20used%20for%20application%20configuration%2C%20package%20manifests%2C%20and%20data%20serialization. "Share on Pinterest")[Email](<mailto:?subject=TOML&body=Check out this article: https%3A%2F%2Fmkabumattar.com%2Fcheatsheets%2Ftoml>)

## Comments

## You might also enjoy

More posts on similar topics

## [YAML](/cheatsheets/yaml)

-   [Mohammad Abu Mattar](/authors/mohammad-abu-mattar)
-   Data Format
-   YAML
-   Configuration
-   Data Serialization
-   DevOps
-   Infrastructure

YAML (YAML Ain't Markup Language) is a human-friendly data serialization language widely used for configuration files, data exchange, and infrastructure-as-code. It emphasizes readability and uses ind

#YAML#Configuration#Data Serialization+6 tags

[read more](/cheatsheets/yaml)

## [JSON](/cheatsheets/json)

-   [Mohammad Abu Mattar](/authors/mohammad-abu-mattar)
-   Data Format
-   JSON
-   Data Serialization
-   Web API
-   Configuration

JSON (JavaScript Object Notation) is a lightweight, text-based data exchange format. It's universally supported across programming languages and provides a simple, readable way to structure and transm

#JSON#Data Format#Data Serialization+5 tags

[read more](/cheatsheets/json)

## [Markdown](/cheatsheets/markdown)

-   [Mohammad Abu Mattar](/authors/mohammad-abu-mattar)
-   Markup Language
-   Markdown
-   Documentation
-   Formatting
-   Content Creation
-   Writing

Markdown is a lightweight markup language for writing formatted content with a simple, readable syntax. It was created for writing on the web, and is now used in documentation, blogs, and note-taking

#Markdown#Formatting#Text+6 tags

[read more](/cheatsheets/markdown)

## [RegEx](/cheatsheets/regex)

-   [Mohammad Abu Mattar](/authors/mohammad-abu-mattar)
-   Tools
-   Regular Expressions
-   Text Processing
-   Pattern Matching
-   Development

Regular expressions (regex or regexp) are patterns used to match character combinations in strings. They handle pattern matching, validation, and text processing across nearly all programming language

#RegEx#Regular Expressions#Pattern Matching+5 tags

[read more](/cheatsheets/regex)

## [Python](/cheatsheets/python)

-   [Mohammad Abu Mattar](/authors/mohammad-abu-mattar)
-   Programming Language
-   Python
-   Scripting
-   Object Oriented
-   Web Development
-   Data Science

Python is an interpreted, high-level programming language known for its readability and simplicity. It supports multiple programming paradigms including procedural, object-oriented, and functional pro

#Python#Programming#Scripting+6 tags

[read more](/cheatsheets/python)

## [Go](/cheatsheets/go)

-   [Mohammad Abu Mattar](/authors/mohammad-abu-mattar)
-   Programming Language
-   Go
-   Systems Programming
-   Web Development
-   Backend
-   Concurrency

Go is a statically typed, compiled programming language designed with simplicity and efficiency in mind. It excels at concurrent programming, which makes it a good fit for fast, scalable server applic

#Go#Golang#Programming+6 tags

[read more](/cheatsheets/go)

6 related posts