tinydb

library4.9.0pypypi✓ verified 28d ago

TinyDB is a lightweight, document-oriented NoSQL database for Python, optimized for simplicity and happiness. It stores data in human-readable JSON files and is designed for small applications that don't require a full-featured database server. Currently in maintenance mode (v4.8.2), it focuses on bugfixes and community-contributed features, with new releases for minor updates and patches.

database serialization

pip install tinydb

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · TINYDB

tinydb

databasepythonv4.9.0

Install

1.5s avg

Import

18ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v4.9.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.020s · 18MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.016s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

TinyDB

✓ from tinydb import TinyDB

Query

✓ from tinydb import Query

This quickstart demonstrates how to initialize a TinyDB database, insert, query, update, and delete documents using `TinyDB` and `Query` objects. It saves data to a local JSON file.

from tinydb import TinyDB, Query import os db_file = 'my_db.json' # Clean up previous db file for fresh run if os.path.exists(db_file): os.remove(db_file) # Initialize database db = TinyDB(db_file) # Insert documents db.insert({'name': 'Alice', 'age': 30, 'city': 'New York'}) db.insert({'name': 'Bob', 'age': 24, 'city': 'London'}) db.insert({'name': 'Charlie', 'age': 30, 'city': 'Paris'}) # Query documents User = Query() alice = db.search(User.name == 'Alice') print(f"Alice: {alice}") people_in_30s = db.search(User.age >= 30) print(f"People aged 30 or more: {people_in_30s}") # Update documents db.update({'age': 31}, User.name == 'Alice') alice_updated = db.search(User.name == 'Alice') print(f"Alice after update: {alice_updated}") # Delete documents db.remove(User.name == 'Bob') all_users = db.all() print(f"All users after Bob's removal: {all_users}") # Clean up after example os.remove(db_file)

Debug

Known issues

breakingVersion 4.0 introduced significant API changes, including renaming table management methods (e.g., `purge_tables` to `drop_tables`, `Table.purge()` to `Table.truncate()`) and changes to how `TinyDB` is initialized. Python 2 support was also dropped.

fix

Consult the TinyDB v4.0 upgrade guide for a full list of changes and adapt code accordingly. Ensure Python 3.8+ is used.

affects: >=4.0.0

breakingVersion 3.0 changed querying syntax. `where('...').contains('...')` became `where('...').search('...')`. `where('foo').has('bar')` was replaced by property access (`where('foo').bar` or `Query().foo.bar`) or dictionary access (`Query()['a.b.c']`). Explicit `exists()` is now required to check for key existence. External packages are needed for `SmartCacheTable` and serialization features.

fix

Update query methods to the new syntax. If using `SmartCacheTable` or advanced serialization, install `tinydb-smartcache` or `tinydb-serialization` respectively.

affects: >=3.0.0

gotchaWhen using property access for queries (e.g., `Query().field_name`), adding new query operations in later TinyDB versions might break code if your field name matches a new operation name (e.g., `Query().map` could break if a `map` operation is introduced).

fix

For document fields that might conflict with future query operation names, use dictionary-style access: `Query()['field_name']` instead of `Query().field_name`.

affects: All versions

gotchaTinyDB is not designed for concurrent access from multiple processes or threads without external tools. Direct concurrent writes can lead to data corruption.

fix

For multi-process/multi-thread scenarios, consider using `tinyrecord` (an external library) or ensuring proper locking mechanisms are implemented outside TinyDB to prevent race conditions.

affects: All versions

gotchaWriting individual records using `db.insert()` can be very slow due to file I/O overhead for each operation.

fix

For inserting multiple documents, use `db.insert_multiple()` with a list of documents to improve performance significantly.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'tinydb'

The `tinydb` package has not been installed in your current Python environment.

fix

pip install tinydb

NameError: name 'Query' is not defined

The `Query` class, which is essential for defining search criteria in TinyDB, has not been imported.

fix

from tinydb import TinyDB, Query

TypeError: cond must be a Query instance, got <class 'str'>

Filtering methods like `get()`, `search()`, `update()`, or `remove()` require a `Query` object for specifying conditions, not a plain string.

fix

db.get(Query().name == 'Alice')

TypeError: update() missing 1 required positional argument: 'cond'

The `update` method requires a condition (`cond`) defined with `Query` to specify which documents should be modified.

fix

db.update({'age': 31}, Query().name == 'Alice')

TypeError: Document must be a dictionary, got <class 'list'>

The `db.insert()` method expects a single dictionary as a document, not a list of documents.

fix

db.insert_multiple([{'name': 'Alice'}, {'name': 'Bob'}])

Upgrade

Version history

4.9.0latest on PyPI · released Aug 6, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

36 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/msiemens/tinydb ↗

packagehttps://pypi.org/project/tinydb/ ↗

docshttps://tinydb.readthedocs.org/ ↗

changeloghttps://tinydb.readthedocs.io/en/latest/changelog.html ↗