Installation#

handcalcs is a pure-Python package on PyPI.

$ pip install handcalcs

or, with uv:

$ uv add handcalcs

Optional extras#

Extra	Install	Adds
`excel`	`pip install "handcalcs[excel]"`	XlsxWriter, needed by the Excel renderer to write `.xlsx` files
`word`	`pip install "handcalcs[word]"`	python-docx, needed by the Word renderer to write `.docx` files
`exporters`	`pip install "handcalcs[exporters]"`	nb-hideinputs, Jupyter export options that hide input cells
`doc`	`pip install "handcalcs[doc]"`	Sphinx and the theme used to build these docs

Using handcalcs in Jupyter#

handcalcs does not install Jupyter itself. Install JupyterLab (or Notebook) in the same environment:

$ pip install handcalcs jupyterlab

Then, in a notebook, import handcalcs registers the %%render cell magic. See the Jupyter interface.

Jupyter typesets the default Markdown output with MathJax, so no LaTeX installation is needed to see rendered calculations. You only need a LaTeX distribution if you export the notebook to PDF through LaTeX, or compile the output of the LaTeX renderer yourself.

Checking the installation#

>>> from handcalcs import HandCalcs
>>> from handcalcs.renderers import ASCIIRenderer
>>> print(HandCalcs(ASCIIRenderer()).demo()[:120])

demo() renders a built-in example calculation with whichever renderer you give it, which is also a quick way to compare renderers.

Next: How handcalcs reads your code.