Cover art by Joshua Hoiberg

handcalcs:
Python calculations,
as though you wrote them by hand.

handcalcs turns ordinary Python calculation code into a formatted calculation: the symbolic formula, then the formula with every value substituted in, then the result. Because the substitution step is shown, anyone can check the calculation by hand.

The same calculation can go to different renderers: Markdown and LaTeX for Jupyter and documents, HTML for web pages, ASCII text for terminals and logs, a live, formula-based Excel worksheet and Word documents. You can restyle the built-in renderers or write your own.

v2.0.0 Pre-release out now!

This readme has been uodated to reflect the changes in handcalcs v2.

As of 2026-10-29, the second release candidate is available for install:

pip install "handcalcs==2.0.0rc2"

or

pip install --pre handcalcs

Read the v2 documentation: getting started, every renderer, a cookbook of recipes, and how to customize or write a renderer.

Example

from math import sqrt   # hc: -i
## Hypotenuse of a right triangle
# Both sides are measured from the site drawings.
a = 2.5  # Side a, in m
b = 4.0  # Side b, in m
c = sqrt(a**2 + b**2)

In Jupyter this is typeset as maths. With the ASCII renderer it reads:

==============================
Hypotenuse of a right triangle
==============================

Both sides are measured from the site drawings.
a = 2.5 (Side a, in m)
b = 4 (Side b, in m)
c = √(a² + b²) = √(2.5² + 4²) = 4.717

Installing

pip install "handcalcs>=2.0.0rc2"

handcalcs 2.0 is a release candidate, so ask for it by version: a plain pip install handcalcs installs 1.x. handcalcs needs Python 3.11 or newer. Extras add the Excel and Word renderers (handcalcs[excel], handcalcs[word]) and Jupyter export options (handcalcs[exporters]). See Installation.

Quick start

In Jupyter, import handcalcs once, then start any cell with %%render:

import handcalcs

%%render
a = 2
b = 3
c = 2*a + b/3

From a script, render a string or a .py file with any renderer:

import pathlib
from handcalcs import HandCalcs
from handcalcs.renderers import LatexRenderer

latex = HandCalcs(LatexRenderer())(pathlib.Path("beam.py"))

On a function, @handcalc(renderer) returns the result and the rendered calculation.

Renderers

Markdown (the Jupyter default), LaTeX, HTML, ASCII text, a live formula-based Excel workbook, and Word documents with native equations. Subclass one to change its look, or write your own. See Renderers.

Upgrading from handcalcs 1.x

handcalcs 2 is a rewrite around a parsed node tree and pluggable renderers. Most notebooks need only a few changes: import handcalcs instead of import handcalcs.render, and # hc: comment commands instead of %%render arguments. See Coming from handcalcs v1.

Gotchas

Jupyter cells can run out of order. handcalcs looks up values in the notebook's namespace, so if you re-use variable names, a cell run out of order can render a beautiful but completely incorrect calculation. Run your notebook top to bottom before you rely on it.

If you use handcalcs for any kind of reporting that may become a legal document (e.g. design engineering calculations), it is up to YOU to ensure that the results are what you expect them to be. handcalcs is free and open-source software, and the author(s) are not responsible for incorrect calculations that result from its use.

That said, the whole point of showing the substitution is to make calculations easy to check by hand.

YouTube tutorials

These cover handcalcs 1.x; the ideas carry over.

• Getting Started with handcalcs (assumes zero Python knowledge)
• Engineering Calculations: handcalcs-on-Jupyter vs. Excel

License

Apache 2.0. See LICENSE.