DataJoint Documentation
Official documentation for the DataJoint Library 2.0+ β open-source software for building scientific data pipelines.
π Live site: https://docs.datajoint.com
Upgrading from pre-2.0? See the Migration Guide
About DataJoint
DataJoint is a Python framework for scientific data pipelines built on the Relational Workflow Model. For installation, tutorials, and complete documentation, visit docs.datajoint.com.
Documentation Structure
This repository contains the source for the DataJoint documentation, organized using the DiΓ‘taxis framework:
Local Development
Docker (Recommended)
# Clone repositories
git clone https://github.com/datajoint/datajoint-docs.git
git clone https://github.com/datajoint/datajoint-python.git
cd datajoint-docs
# Start live preview at http://localhost:8000
MODE="LIVE" docker compose up --build
# Build static site (optional)
# MODE="BUILD" docker compose up --build
The Docker environment includes MySQL, PostgreSQL, MinIO, and all dependencies.
Native Python
Prerequisites: Python 3.10+, and a supported backend β MySQL 8.0+ or PostgreSQL (peer backends)
# Setup
git clone https://github.com/datajoint/datajoint-docs.git
cd datajoint-docs
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r pip_requirements.txt
# Configure credentials
mkdir -p .secrets
echo "your_username" > .secrets/database.user
echo "your_password" > .secrets/database.password
chmod 600 .secrets/*
# Start live preview at http://localhost:8000
mkdocs serve
Contributing
Contributions welcome! See contribution guidelines.
Quick fixes: Fork, edit markdown in src/, submit PR.
Single notebook: Re-execute one notebook in place:
docker compose exec docs jupyter nbconvert --to notebook --execute --inplace \
/main/src/tutorials/YOUR_NOTEBOOK.ipynb
Notebook execution policy
Tutorial and how-to notebooks under src/tutorials/ and src/how-to/ are
committed with their executed cell outputs. The static site renders these
outputs verbatim via mkdocs-jupyter β the build container does not execute
notebooks, so the rendered page always matches what was committed.
Refresh outputs whenever the DataJoint version pinned in mkdocs.yaml
(extra.datajoint_version) changes, or whenever a tutorial's code changes:
# Re-execute against the bind-mounted local datajoint-python checkout
DJ_PYTHON_PATH=../datajoint-python MODE=EXECUTE docker compose up --build
DJ_PYTHON_PATH=../datajoint-python MODE=EXECUTE_PG docker compose up --build
A guard script flags notebooks whose committed DataJoint X.Y.Z connected
banner doesn't match extra.datajoint_version:
python scripts/check_notebook_versions.py
Notes on the execution environment:
- Credentials. The Compose databases use the password
tutorial β
root for MySQL (MYSQL_ROOT_PASSWORD) and postgres for PostgreSQL (POSTGRES_USER /
POSTGRES_PASSWORD), both set in docker-compose.yaml. MODE=EXECUTE* supplies them to the
notebooks automatically; you only need them to connect to a Compose database from outside it.
- Graphviz.
dj.Diagram's notebook display calls the Graphviz dot binary, which the docs
image installs. This is why committed diagram outputs always render, and why the same cell
fails on a host without Graphviz β see
Installation β Troubleshooting.
- DataJoint version.
pip_requirements.txt installs datajoint@master, so regenerated
outputs track the development branch rather than the last release.
Related
Citation
Yatsenko D, Nguyen TT. DataJoint 2.0: A Computational Substrate for Agentic Scientific Workflows. arXiv:2602.16585. 2026. doi: 10.48550/arXiv.2602.16585 β RRID:SCR_014543
Full citation information: docs.datajoint.com/about/citation/
License