Installation¶

This page describes how you can install Handprint on your computer. After installation, you will also need to perform some configuration steps described elsewhere.

Preliminary requirements¶

Handprint is written in Python 3 and makes use of some additional Python software libraries that are installed automatically during the installation steps. It also assumes a macOS, Windows or Linux environment, and a working Internet connection.

The instructions below assume you have a Python interpreter version 3.8 or higher installed on your computer; if that’s not the case, please first install Python and familiarize yourself with running Python programs on your system. If you are unsure of which version of Python you have, you can find out by running the following command in a terminal and inspecting the results:

# Note: on Windows, you may have to use "python" instead of "python3"
python3 --version

Note for Mac users: if you are using macOS Catalina (10.15) or later and have never run python3, then the first time you do, macOS will ask you if you want to install the macOS command-line developer tools. Go ahead and do so, as this is the easiest way to get a recent-enough Python 3 on those systems.

Installation instructions¶

There are multiple ways of installing Handprint, ranging from downloading a self-contained, single-file, ready-to-run program, to installing it as a typical Python program using pip. Please choose the alternative that suits you.

Approach 1: using the standalone Handprint executables¶

Beginning with version 1.5.1, runnable self-contained single-file executables are available for select operating system and Python version combinations – to use them, you only need a Python 3 interpreter and a copy of Handprint, but do not need to run pip install or other steps.

MacOS¶

Visit the Handprint releases page and look for the ZIP files with names such as (e.g.) handprint-1.5.4-macos-python3.8.zip. Then:

Download the one matching your version of Python
Unzip the file (if your browser did not automatically unzip it for you)
Open the folder thus created (it will have a name like handprint-1.5.4-macos-python3.8)
Look inside for handprint and move it to a location where you put other command-line programs (e.g., /usr/local/bin)

Linux¶

Visit the Handprint releases page and look for the ZIP files with names such as (e.g.) handprint-1.5.4-linux-python3.8.zip. Then:

Download the one matching your version of Python
Unzip the file (if your browser did not automatically unzip it for you)
Open the folder thus created (it will have a name like handprint-1.5.4-linux-python3.8)
Look inside for handprint and move it to a location where you put other command-line programs (e.g., /usr/local/bin)

Windows¶

Standalone executables for Windows are not available at this time. If you are running Windows, please use one of the other methods described below.

Approach 2: using `pipx`¶

You can use pipx to install Handprint. Pipx will install it into a separate Python environment that isolates the dependencies needed by Handprint from other Python programs on your system, and yet the resulting handprint command wil be executable from any shell – like any normal application on your computer. If you do not already have pipx on your system, it can be installed in a variety of easy ways and it is best to consult Pipx’s installation guide for instructions. Once you have pipx on your system, you can install Handprint with the following command:

pipx install handprint

Pipx can also let you run Handprint directly using pipx run handprint, although in that case, you must always prefix every Handprint command with pipx run. Consult the documentation for pipx run for more information.

Approach 3: using `pip`¶

If you prefer, you can install Handprint with pip. If you don’t have pip package or are uncertain if you do, please consult the pip installation instructions. Then, to install or upgrade Handprint from the Python package repository, run the following command:

python3 -m pip install handprint --upgrade