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

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.

This repository contains the source for the DataJoint documentation, organized using the Diátaxis framework:

• Tutorials — Learn by building real pipelines
• How-To Guides — Practical task-oriented guides
• Explanation — Understanding concepts and design
• Reference — Specifications and API documentation

# 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.

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

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

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.

• datajoint-python — Core library
• DataJoint Elements — Neuroscience pipeline modules
• datajoint.com — Commercial support

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/

• Documentation: CC BY 4.0
• DataJoint software: Apache 2.0 (LGPLv2.1 prior to v2.0)