---
id: python-toon
version: "0.1.3"
license: MIT
license_treatment: permissive
maintenance: aging
---

# python-toon — TOON (Token-Oriented Object Notation) encoder/decoder for Python - Bidirectional JSON-to-TOON converter optimized for LLMs

License: permissive · Maintenance: aging · Downloads: 605.2K/mo

## What it is and what it does

python-toon is a bidirectional encoder/decoder for TOON, a data format that combines YAML-style indentation for nested objects with CSV-like tabular format for uniform arrays. It targets LLM token efficiency by eliminating redundant punctuation (braces, brackets, most quotes) while maintaining semantic clarity. The package provides both a Python API (encode/decode functions) and a command-line tool for converting between JSON and TOON formats.

The format supports nested objects, primitive arrays with length markers, tabular arrays (uniform object collections), and mixed arrays. It implements the official TOON specification with strict validation by default, optional lenient parsing, and configurable delimiters (comma, tab, pipe). Since its first release in October 2025, it has reached version 0.1.3 and supports Python 3.8 through 3.12.

Use it for:

- Prepare structured data for LLM prompts where token count directly affects API cost or response latency.
- Convert existing JSON datasets to TOON format for more efficient LLM ingestion via CLI or programmatic API.
- Encode tabular data (lists of uniform objects) into compact CSV-like TOON format for batch LLM processing.
- Bidirectionally convert between JSON and TOON in data pipelines that feed language models.
- Validate TOON-formatted input with strict mode or parse lenient TOON variants with relaxed validation.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Encodes and decodes TOON (Token-Oriented Object Notation), a compact data format designed to represent structured data in 30-60% fewer tokens than JSON, optimized for transmission to Large Language Models.

Yes, if you are building LLM applications where token efficiency matters and you want a standards-compliant TOON implementation. The package is lightweight (no dependencies), well-documented, and covers both API and CLI use cases. The aging maintenance status (283 days since last commit) is a minor concern for a stable format encoder, but the unarchived repository and recent release history suggest it is not abandoned. No known security vulnerabilities.

## Install

pip install python-toon
uv add python-toon
poetry add python-toon

## Installing python-toon

Before you install: Low friction: pure Python wheel with no runtime dependencies. Maintenance status is aging—last commit was 283 days ago—but the repository remains active and unarchived with 340 stars.

License in practice: MIT license (permissive): you can use, modify, and distribute this package freely in commercial and private projects, with minimal restrictions.

Quickstart:

pip install python-toon

from toon import encode, decode

data = {"name": "Alice", "age": 30}
toon_str = encode(data)
print(toon_str)  # name: Alice\nage: 30

recovered = decode(toon_str)
print(recovered)  # {'name': 'Alice', 'age': 30}

Verify before relying:

- Whether the 30-60% token reduction claim has been independently validated against real LLM tokenizers.
- Performance characteristics (encoding/decoding speed) on large datasets or deeply nested structures.
- Compatibility guarantees with the official TypeScript TOON implementation beyond the stated 100% output compatibility.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 605.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

token-efficient data format, JSON to TOON converter, LLM-optimized encoding, compact structured data format, YAML-like object notation, reduce tokens for LLM, TOON encoder decoder, llm-optimization, data-serialization, token-efficiency

[View on SkillFed](https://skillfed.io/packages/python-toon) · [View on PyPI](https://pypi.org/project/python-toon/)