calkit-python

Documentation | Tutorials | Discussions

Typical research workflows are horizontally-siloed, i.e., various stages--data collection, analysis, writing--are performed in disconnected systems, turning research into a slow, error-prone, and tedious waterfall process.

Calkit helps you integrate code, data, figures, results, publications, and more into a cohesive, traceable, and portable knowledge creation system, so every output can be traced back to its source (provenance) and reproduced with a single command.

With industry standard tools combined into a unified and simplified experience tailored for research, you can reap the rewards of reproducibility and automation without the cognitive overhead.

pipeline

Features

A simplified version control interface that unifies Git and DVC (Data Version Control), so everything can be kept in the same project repository. This way, code doesn't need to be siloed away from other important artifacts like datasets, models, figures, or article PDFs, allowing you to work on all parts of a project without hopping around to different tools.
Computational environment management with support for many languages and environment managers: Conda, Docker, uv, Julia, Renv, and more. No need to create and update environments on your own. Calkit will handle them as needed.
An environment-aware build system or pipeline with a simple declarative syntax and output caching so you don't need to think about which steps or stages need to be rerun after changing any part of the project. Simply call calkit run. Compose your pipeline from many different kinds of stages, including simple scripts, commands, Jupyter Notebooks, LaTeX, and more.
A complementary self-hostable and GitHub-integrated hub to facilitate backup, collaboration, and sharing throughout the entire research lifecycle.
Overleaf integration, so analysis, visualization, and writing can all stay in sync (no more manual uploads!)
Support for running on high performance computing (HPC) systems that use PBS or SLURM schedulers.
Support for automated running with GitHub Actions.
Extensions for doing all of the above graphically in JupyterLab and VS Code.
A browser extension for collecting references directly to BibTeX (optionally synced with Zotero), viewing DVC-stored files on GitHub, and syncing figures and results with Overleaf directly in Chrome, Microsoft Edge, and more.

Installation

On Linux, macOS, or Windows Git Bash, install Calkit and uv (if not already installed) with:

curl -LsSf install.calkit.org | sh

Or with Windows Command Prompt or PowerShell:

powershell -ExecutionPolicy ByPass -c "irm install-ps1.calkit.org | iex"

If you already have uv installed, install Calkit with:

uv tool install calkit-python

You can also install with your system Python:

pip install calkit-python

To effectively use Calkit, you'll want to ensure Git is installed and properly configured. You may also want to install Docker, since that is the default method by which LaTeX environments are created. If you want to use a Calkit hub for collaboration and backup as a DVC remote, you can connect to the hub with:

calkit hub login

If you use AI agents like Claude, Copilot, or Codex, see AI tools to learn how to install agent skills for working with Calkit.

Use without installing

If you want to use Calkit without installing it, you can use uv's uvx command to run it directly:

uvx ck9 --help

Nix

Calkit ships a flake at the root of its repo, so Nix users can pull the CLI into their environments alongside their other tools.

Run it ad hoc without installing:

nix run github:calkit/calkit -- --help

Drop into a shell that has calkit, git, and uv on PATH:

nix shell github:calkit/calkit

Add it to your own flake.nix as an input:

{
  inputs.calkit.url = "github:calkit/calkit";
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";

  outputs = { self, nixpkgs, calkit }: {
    devShells.x86_64-linux.default =
      nixpkgs.legacyPackages.x86_64-linux.mkShell {
        packages = [ calkit.packages.x86_64-linux.default ];
      };
  };
}

Then nix develop will give you a shell with the Calkit CLI ready to use. To pin a specific Calkit release inside the shell, set the CALKIT_VERSION environment variable (e.g. CALKIT_VERSION=0.41.0) before invoking calkit.

The flake is currently a thin wrapper around uvx --from calkit-python calkit. It depends on uv from nixpkgs and fetches the published wheel from PyPI on first use. This trades a fully Nix-native build for zero version-drift maintenance, and avoids the macOS docx2pdf / appscript and JupyterLab labextension build issues that block a pure nixpkgs derivation today. If you want a fully nixpkgs-native build, see the community calkit-nix flake.

Nix isn't supported natively on Windows; run Calkit inside WSL2 and use the flake there.

Running against a specific version

If a project requires a Calkit version other than the one you have installed, use the top-level --use-version flag to re-invoke the CLI under that release without changing your installation:

calkit --use-version 0.38 run

This re-execs the CLI via uvx --from calkit-python@<version> calkit, so it requires uv on PATH. You can also declare a minimum version in calkit.yaml; see Pinning the Calkit CLI version.

Calkit Assistant

For Windows users, the Calkit Assistant app is the easiest way to get everything set up and ready to work in VS Code, which can then be used as the primary app for working on all scientific or analytical computing projects.

Calkit Assistant

Quickstart

!!! note ck is an abbreviated alias for the calkit executable. All calkit commands can be run as ck instead, e.g., ck save -am "...".

From an existing project

If you want to use Calkit with an existing project, navigate into its working directory and use the xr command to start executing and recording your scripts, notebooks, LaTeX files, etc., as reproducible pipeline stages. For example:

calkit xr scripts/analyze.py

calkit xr notebooks/plot.ipynb

calkit xr paper/main.tex

Calkit will attempt to detect environments, inputs, and outputs and save them in calkit.yaml. If successful, you'll be able to run the full pipeline with:

calkit run

Next, make a change to e.g., a script and look at the output of calkit status. You'll see that the pipeline has a stage that is out-of-date:

---------------------------- Pipeline ----------------------------
analyze:
        changed deps:
                modified:           scripts/analyze.py

This can be fixed with another call to calkit run.

You can save (add and commit) all changes with:

calkit save -am "Add to pipeline"

Fresh from a Calkit project template

Create a new project from the calkit/example-basic template with:

calkit new project my-research \
    --title "My research" \
    --template calkit/example-basic \
    --hub

Note the --hub flag requires a hub connection to be set up, but can be omitted if the project doesn't need to be backed up to the hub or shared with collaborators. Hub integration can also be set up later.

Next, move into the project folder and run the pipeline, which consists of several stages defined in calkit.yaml:

cd my-research
calkit run

Next, make some edits to a script or LaTeX file and run calkit status to see what stages are out-of-date. For example:

---------------------------- Pipeline ----------------------------
build-paper:
        changed deps:
                modified:           paper/paper.tex

Execute calkit run again to bring everything up-to-date.

To back up or save the project, call:

calkit save -am "Run pipeline"

With an AI coding agent

Simply tell the AI agent:

Turn this folder into a Calkit project

Create me a new Calkit project for investigating...

Get involved

We welcome all kinds of contributions! See CONTRIBUTING.md to learn how to get involved.

Acknowledgements

Calkit is supported by the Caltech Schmidt Academy of Software Engineering.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

calkit_python-0.47.1.tar.gz (25.3 MB view details)

Uploaded Sep 11, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

calkit_python-0.47.1-py3-none-any.whl (1.0 MB view details)

Uploaded Sep 11, 2026 Python 3

File details

Details for the file calkit_python-0.47.1.tar.gz.

File metadata

Download URL: calkit_python-0.47.1.tar.gz
Upload date: Sep 11, 2026
Size: 25.3 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for calkit_python-0.47.1.tar.gz
Algorithm	Hash digest
SHA256	`c30d27f29408ffe1728115ed4a9a3689978fcd45a8c1fb1af2f6e1f916c1db7f`
MD5	`7156acd3e9ac387d258d7bc738d0b80b`
BLAKE2b-256	`133043bb2d430925d636c96bb2cd2c8cf2c55aa39ce412e37b25b11e44ffad75`

See more details on using hashes here.

Provenance

The following attestation bundles were made for calkit_python-0.47.1.tar.gz:

Publisher: publish.yml on calkit/calkit

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: calkit_python-0.47.1.tar.gz
- Subject digest: c30d27f29408ffe1728115ed4a9a3689978fcd45a8c1fb1af2f6e1f916c1db7f
- Sigstore transparency entry: 2795874548
- Sigstore integration time: Sep 11, 2026
Source repository:
- Permalink: calkit/calkit@fb8c75f993e729f3d4a4846dd61d11a55b6ab804
- Branch / Tag: refs/tags/v0.47.1
- Owner: https://github.com/calkit
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@fb8c75f993e729f3d4a4846dd61d11a55b6ab804
- Trigger Event: release