Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Alkali was featured on PythonBytes episode #119!

Alkali is a database engine, written in Python 3. It's raison d'être is to provide a Django-like ORM while controlling the on disk format. If you already have your data in a real database like Postgres then you'll want SQLAlchemy, if however, your data is in json/yaml/csv/other/etc files then Alkali might be exactly what you're looking for.

Full documentation at

For some examples, please go straight to the quickstart guide:

Here's a teaser to whet your appetite.

import os
from alkali import Database, Model, fields, tznow

class Entry(Model):

   date    = fields.DateTimeField(primary_key = True)
   title   = fields.StringField()
   body    = fields.StringField()
   created = fields.DateTimeField(auto_now_add=True)

db = Database(models=[Entry], save_on_exit=True)

e = Entry(date=tznow(), title="my first entry", body="alkali is pretty good")    # adds model instance to Entry.objects

title = Entry.objects.filter(date__le=tznow()).first().title
assert title == "my first entry"
assert os.path.getsize('Entry.json')


If you're reading this then you probably didn't install with pip install alkali and get on with your life. You probably want to be able edit the code and run tests and whatnot.

In that case run: pip install -e .[dev]


If you want to be able to build the docs then also run

pip install -e .[docs]
make html


During development pytest was the runner of choice but any unit test runner should work.


  • pytest run all tests
  • pytest -s to see stdout (any print statements)
  • pytest --cov to see test coverage
  • pytest -k test_1 to run all tests named test_1
  • pytest -k test_1 alkali/tests/ to run test_1 in