Setting Up

Outline

↑

There are four parts to being able to use protograf on your own machine:

  1. Install the correct version of Python

  2. Install and set-up protograf

  3. Install a text editing program

  4. Install a PDF viewer

Its possible that you may already have one or more of these programs installed, but please follow the documentation here to ensure they will work with/for protograf.

Python in 1 minute

↑

Why do you need Python installed before starting?

When you work with Python, or software made with Python, you do not have executable files, such as the typical .exe ones you find on Windows (or .app on macOS). Instead, Python itself is first loaded and then it “runs” your Python file/script/program on your behalf. So, running any Python script, such as the ones created for protograf requires that you first install Python itself.

Python itself is composed of many built-in libaries, or packages, each of which handles some aspect of a program. Python also is designed to be extended by adding-on additional packages written by other programmers; PyMuPDF, for example, is one of those, as is protograf. Python does not come with those packages built-in — you need to install them after Python itself has been installed.

Installing Python packages is handled by a tool called pip — the Python Installation Package — which is typically installed at the same time as Python itself.

Opening a Terminal

↑

In order to install Python and use protograf, you will need to use a command-line window or Terminal.

The way that you open a terminal window depends on your operating system:

  • For Windows users - go to “Start -> Run” (On Windows 7 to 10, press “WindowsKey+R”), or use the search box at the bottom of the Start menu, and then enter cmd — Windows should now show you the option to run a Command Prompt window.

  • For Mac OS X users - go to your Applications/Utilities folder and choose “Terminal”.

  • For Linux users; you should already know how to open a Terminal!

Installing Python

↑

protograf requires a device e.g. laptop or desktop — but probably not a smart phone — that has the correct version of Python (version 3.13 or higher) installed. This section guides you through such an install.

Note

These are minimal guidelines; in case of any doubt or confusion, please refer to the full documentation of the tools that are referenced here!

Linux users

You likely already have a version of Python installed, but it is strongly recommended that you set up a new version in a “virtual environment” to work with protograf.

To do this, you can use a modern tool such as uv; see https://ubuntushell.com/install-uv-python-package-manager/

You can then use uv to install an updated version of Python into a virtual environment. After opening a Terminal:

uv venv --python 3.13

uv has extensive documentation at https://docs.astral.sh/uv/

Windows Users

It is strongly recommended that, even if you already have Python installed, that you set up a version in a “virtual environment” to work with protograf This has the advantage of not interfering with, or even accidentally altering, what is already working.

Option 1: uv

A quick and easy way to get going with a virtual environment is to use uv.

Follow the install guide uv — see for example https://docs.astral.sh/uv/getting-started/installation/#standalone-installer

After opening a Terminal use uv to install the right version of Python in a virtual environment.

The example below assumes you are working as the user “Sam”.

In the terminal window you have opened, you will see a prompt i.e. text followed by small _:

c:\Users\Sam>

Now install Python by entering:

uv venv --python 3.13

After a successful install, you will be prompted with:

Activate with: .venv\Scripts\activate

You can activate the virtual environment by typing:

.venv\Scripts\activate

And the prompt should change to:

(Sam) C:\Users\Sam>

which indicates that the virtual environment is now ready for you to install software and run Python scripts.

uv has extensive documentation at https://docs.astral.sh/uv/

Option 2: miniconda

The miniconda software is also a fairly simple way of starting to use Python.

Follow https://docs.anaconda.com/miniconda/miniconda-install/ for instructions on downloading and running the installer.

Make sure you choose a version that will install Python 3.13 or higher (3.13, 3.14, etc.).

Follow their documentation there to ensure that Python is working after the installation is complete.

Make sure you can use miniconda to setup and activate a new virtual environment.

Mac Users

The program author has no access to a MacOS, and so cannot be sure this software will work there.

It is suggested to follow the approach outlined for Windows and install uv.

There is a helpful guide on working with Python from pyLadies; see: http://www.pyladies.com/blog/Get-Your-Mac-Ready-for-Python-Programming/

Testing that Python is installed

After opening a Terminal, and activating the virtual environment:

python --version

You should see something like:

Python 3.13.1

The exact number after the “13” does not matter.

You can now close the command-line window.

Other software installs

↑

PDF Viewer

You will also need a program that can display PDF files; for example, Adobe Acrobat (cross-platform), or Evince (Linux), or Preview (Mac), or Foxit (Windows).

Most modern web browsers should also be able to open and display PDF files.

Hint

While not a requirement, it appears that Sumatra PDF viewer — available at https://www.sumatrapdfreader.org/download-free-pdf-viewer — is a useful one for Windows users, as it supports “live reloading” i.e. each time you make changes to your protograf script the PDF will automatically refresh if the script output is already loaded into a running instance of the Sumatra PDF viewer.

Text Editor

When you create and edit your scripts, you must not use a word processor such as “Word”, “Pages” or “LibreOffice” — but a text file editor.

For Windows users, it is suggested that you install NotePad++ which is the recommended Windows editor for creating protograf scripts — if you do not already have a tool for editing Python scripts.

On OS X, you could use TextEdit or CotEditor.

A useful editor should be able to color-code your file to make it easier to work with.

Core Fonts (optional)

For Linux users, it is recommended that you install Microsoft’s Core Fonts - see http://mscorefonts2.sourceforge.net/ — Ubuntu users can install these via:

sudo apt-get install ttf-mscorefonts-installer

Installing protograf

↑

Important

Windows users will need to install an additional program - a “DLL” - which is a required dependency. Download the vc_redist.x64.exe file from https://learn.microsoft.com/en-gb/cpp/windows/latest-supported-vc-redist?view=msvc-170#latest-microsoft-visual-c-redistributable-version and follow the installation process!

This package is needed for the SVG export option to work.

After testing that Python is installed, you can install protograf itself via pip.

After opening a Terminal, and activating the virtual environment:

pip install protograf

If you are using uv:

uv pip install protograf

Hint

It might be that protograf gets upgraded/updated after you have installed it for the first time; in this case, if you are using uv you can use this commmand to update it:

uv pip install -U pymupdf

Checking that protograf works

↑

1. Create a test file

To now check that protograf works, you should create a small test file.

Open your text editor and type — or copy and paste — the following, making sure you do not have any spaces at the start of any line!:

from protograf import *
Create()
Text(text="Hello World")
Save()

Hint

If you’re viewing this documentation on the readthedocs website, you can hover over the top-right corner of any colored block of text and click on the icon to automatically copy that block.

Save the file; call it test.py. The .py extension indicates that this is a Python file — this is useful but not absolutely essential!

2. Run file with Python

Now use Python to “run” this test file i.e. after opening a Terminal, and activating the virtual environment, you will need to change to the directory in which the test file was created.

For example, on Windows, you may have saved the file in Documents, so:

(Sam) C:\Users\Sam>cd Documents

Now type:

python test.py

and press the Enter key.

3. View test results

After the test file has been “run”, there should now be a new file created called test.pdf that has been created in the same directory.

You should be able to open and view this PDF file via your PDF viewer. It should be a mostly blank, A4-sized page with the phrase Hello World in a small, Helvetica font near the top-left.

Python in the cloud

↑

If you do not want to install Python, you can try a cloud-based version.

You will need to register on https://www.pythonanywhere.com/ and then use the tools and infrastructure they provide.

Hint

The environment used for pythonanywhere is a Linux-based one and likely to be unfamiliar if you’re a Windows user — especially if you’re not used to working via a “shell” in a Terminal, or command-line, interface.

pythonanywhere provides a terminal (bash) that you can use to install Python packages via pip.

You also have option to edit, or upload files — such as protograf scripts. Once scripts are available there, they can be run in the Terminal.

pythonanywhere has its own documentation to help you work further with it.