---
id: tinydb
version: "4.9.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# tinydb — TinyDB is a tiny, document oriented database optimized for your happiness :)

License: permissive · Maintenance: active · Downloads: 6.9M/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 6.9M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

lightweight json document database, embedded nosql database python, file-based json storage, small project local database, python dict persistence, nosql, embedded-database, json-storage

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