tinydb

What it is and what it does

TinyDB is a document-oriented database written entirely in Python, designed for small applications that would be overkill for a full SQL database or external server. It stores documents as Python dictionaries in JSON files on disk, with no external dependencies or server process required. The API is intentionally simple: you insert dictionaries, query them using a fluent query language with logical operators, and organize data into named tables. It supports middlewares for customization (like caching) and is extensible through custom storage backends.

The package targets developers building small tools, scripts, or applications where a lightweight local database suffices. It has been actively maintained since 2013, supports Python 3.10 through 3.14 and PyPy3, and includes comprehensive test coverage. The project is now in maintenance mode, meaning new architectural features are unlikely, but bugfixes and community contributions continue.

Use it for:

• Store configuration or state for a small CLI tool or desktop application without setting up a database server.
• Persist user data (preferences, cache, local records) in a single-file format that's human-readable and portable.
• Build a quick prototype or MVP that needs structured data storage without the overhead of SQL or MongoDB.
• Write integration tests that need a temporary, isolated database without external dependencies.
• Manage a simple document collection (logs, events, metadata) for a standalone script or microservice.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

TinyDB is a lightweight, pure-Python document database that stores JSON-like dictionaries to local files, with no external dependencies or server required.

Yes, if you're building a small application or tool that needs local document storage without external dependencies. The zero-dependency design, simple API, and active maintenance make it a solid choice for prototypes, scripts, and small projects. Not suitable for applications requiring concurrent writes, complex transactions, or large-scale data—use a proper database for those cases.

Install

tinydb on PyPI

pip install tinydb

uv add tinydb

poetry add tinydb

Installing tinydb

Before you install

Installation is frictionless: the package is pure Python with zero runtime dependencies and ships as a single wheel. Maintenance is active with recent releases, though the project is in maintenance mode—bugfixes and community contributions are still accepted.

License in practice

MIT license is permissive; you can use, modify, and distribute TinyDB freely in commercial and private projects with minimal restrictions.

Quickstart

pip install tinydb

from tinydb import TinyDB, Query
db = TinyDB('/path/to/db.json')
db.insert({'name': 'John', 'age': 22})
User = Query()
results = db.search(User.name == 'John')

Requires Python 3.10 or later; does not support Python 3.9 or earlier.

Verify before relying

• Concurrent write safety and locking behavior under simultaneous access patterns.
• Performance characteristics and scalability limits for datasets beyond typical small-app sizes.
• Storage backend options beyond the default JSON file storage mentioned in the description.

Package facts

Evidence: tinydb-4.9.0-py3-none-any.whl

Keywords: database, nosql

Tags

More Utilities packages