---
id: datafiles
version: "2.5"
license: MIT
license_treatment: permissive
maintenance: active
---

# datafiles — File-based ORM for dataclasses.

License: permissive · Maintenance: active · Downloads: 133.5K/mo

## What it is and what it does

Datafiles bridges Python dataclasses and the filesystem by automatically persisting object state to files and reloading changes from disk. You decorate a dataclass with a file path pattern, then read and write the object normally—changes sync bidirectionally without explicit save/load calls. It supports YAML, JSON, TOML, and JSON5 formats, preserving comments and formatting where possible.

The library is designed for configuration management, test fixtures, version-controlled state, and prototyping data models before committing to a database backend. It depends on ruamel.yaml, tomlkit, json-five, parse, minilog, classproperties, and cached_property to handle format-specific serialization and property introspection.

Use it for:

- Store application configuration in YAML or TOML files that remain human-editable while staying type-safe in Python.
- Load test fixtures from files into dataclass instances, automatically coercing types and validating structure.
- Synchronize application state across machines using file-sharing services by treating the filesystem as a shared data layer.
- Prototype data models with file-based persistence before migrating to a database backend.
- Version-control program state and configuration by keeping dataclass instances synchronized to committed files.

## Worth the install?

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

Datafiles is a file-based ORM that automatically synchronizes Python dataclasses to disk files (YAML, JSON, TOML, JSON5) and back, treating the filesystem as a bidirectional persistence layer with minimal boilerplate.

Yes. Datafiles is actively maintained, has no known vulnerabilities, uses a permissive MIT license, and offers a clean, low-friction way to persist dataclasses to disk with bidirectional sync. Install it if you need automatic file-based persistence for configuration, state, or fixtures; skip it if you require a traditional database or need Python versions below 3.10.

## Install

pip install datafiles
uv add datafiles
poetry add datafiles

## Installing datafiles

Before you install: Low friction: pure Python wheel with seven runtime dependencies (cached_property, classproperties, json-five, minilog, parse, ruamel.yaml, tomlkit). Active maintenance with last commit 2026-08-05 and 213 repository stars; supports Python 3.10–3.14.

License in practice: MIT license (permissive) imposes no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart:

from dataclasses import dataclass
from datafiles import datafile

@datafile("config/{self.name}.yml")
@dataclass
class Config:
    name: str
    value: int = 0

config = Config("app")
config.value = 1  # automatically saved to config/app.yml

Requires Python 3.10 or later (minimum 3.10, maximum <4.0).

Verify before relying:

- Whether round-trip formatting preservation works equally well across all supported formats (YAML, JSON, TOML, JSON5).
- Performance characteristics when synchronizing large dataclass instances or deeply nested structures.
- Behavior when multiple processes or threads modify the same dataclass instance concurrently.

## Package facts

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

## Tags

dataclass file serialization, yaml json config sync, file-based orm python, automatic dataclass persistence, bidirectional file sync, toml yaml dataclass, python object file mapping, dataclass-orm, file-persistence, config-management

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