Installing Algan locally

The standard way of installing Algan is by using Python’s package manager pip to install the latest release from PyPI.

To make it easier for you to follow best practices when it comes to setting up a Python project for your Algan animations, we strongly recommend using a tool for managing Python environments and dependencies. In particular, we strongly recommend using uv.

For the main way of installing Algan described below, we assume that uv is available; we think it is particularly helpful if you are new to Python or programming in general. It is not a hard requirement whatsoever; if you know what you are doing you can just use pip to install Algan directly.

Installing the Python management tool uv

One way to install uv is via the dedicated console installer supporting all large operating systems. Simply paste the following snippet into your terminal / PowerShell – or consult uv’s documentation for alternative ways to install the tool.

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Of course, if you know what you are doing and prefer to setup a virtual environment yourself, feel free to do so!

Important

If you run into issues when following our instructions below, do not worry: check our installation FAQs to see whether the problem is already addressed there – and otherwise go and check how to contact our community to get help.

Installation

Step 1: Installing Python

We first need to check that an appropriate version of Python is available on your machine. Open a terminal to run

uv python install

to install the latest version of Python.

Once installed, we can create a new folder ‘alganimations’ and instantiate a uv virtual environment by running these commands

uv init alganimations
cd alganimations
uv venv

uv will install packages to the virtual environment contained in the current working directory, so make sure you stay in the same working directory throughout the installation process!

Step 2 (optional): Installing LaTeX

LaTeX is a very well-known and widely used typesetting system allowing you to write formulas like

\[\begin{equation*} \frac{1}{2\pi i} \oint_{\gamma} \frac{f(z)}{(z - z_0)^{n+1}}~dz = \frac{f^{(n)}(z_0)}{n!}. \end{equation*}\]

Algan uses LaTeX to generate its text. If you never intend to render text, then you can technically skip this step. Otherwise select your operating system from the tab list below and follow the instructions.

For Windows we recommend installing LaTeX via the MiKTeX distribution. Simply grab the Windows installer available from their download page, https://miktex.org/download and run it.

If you are running MacOS, we recommend installing the MacTeX distribution. The latest available PKG file can be downloaded from https://www.tug.org/mactex/mactex-download.html. Get it and follow the standard installation procedure.

Given the large number of Linux distributions with different ways of installing packages, we cannot give detailed instructions for all package managers.

In general we recommend to install a TeX Live distribution (https://www.tug.org/texlive/). For most Linux distributions, TeX Live has already been packaged such that it can be installed easily with your system package manager. Search the internet and your usual OS resources for detailed instructions.

For example, on Debian-based systems with the package manager apt, a full TeX Live distribution can be installed by running

sudo apt install texlive-full

For Fedora (managed via dnf), the corresponding command is

sudo dnf install texlive-scheme-full

As soon as LaTeX is installed, continue with actually installing Algan itself.

I know what I am doing and I would like to setup a minimal LaTeX installation

You are welcome to use a smaller, more customizable LaTeX distribution like TinyTeX. Algan overall requires the following LaTeX packages to be installed in your distribution:

amsmath babel-english cbfonts-fd cm-super count1to ctex doublestroke dvisvgm everysel
fontspec frcursive fundus-calligra gnu-freefont jknapltx latex-bin
mathastext microtype multitoc physics preview prelim2e ragged2e relsize rsfs
setspace standalone tipa wasy wasysym xcolor xetex xkeyval

Step 3: Installing PyTorch

Algan is built on top of PyTorch, to provide GPU accelerated animations and rendering. Depending on your operating system and GPU hardware, you will need to install different versions of PyTorch.

Head over to https://pytorch.org/get-started/locally/ and you should see a bunch of options to choose from.

  • For the PyTorch build select Stable.

  • Select your operating system.

  • For the package select pip.

  • For the language select Python.

  • For the compute platform, you need to select the right version for your computer’s GPU hardware. If you are using an NVIDIA GPU you want to select the latest version of CUDA. If you are using an AMD GPU you will want to select ROCm. Otherwise, you can select CPU to run without GPU acceleration.

There should now be a pip3 command shown in the “Run this Command” box. Since we are using uv to manage our packages, we need to modify the this command to use uv. Simply replace the pip3 at the start of the command with uv pip. For example, PyTorch shows me the command

pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128

so I would run

uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128

If no error message is shown, then installation was successful and you can move on to installing Algan.

Step 4: Installing Algan

Follow the instructions for your operating system below:

Run this command

uv pip install --extra-index-url https://test.pypi.org/simple/ algan --index-strategy unsafe-best-match

Before we can install Algan, we need to make sure that the system utilities cairo and pkg-config are present. They are needed for the pycairo Python package, a dependency of Algan.

The easiest way of installing these utilities is by using Homebrew, a fairly popular 3rd party package manager for MacOS. Check whether Homebrew is already installed by running

brew --version

which will report something along the lines of Homebrew 4.4.15-54-... if it is installed, and a message command not found: brew otherwise. In this case, use the shell installer as instructed on Homebrew’s website, or get a .pkg-installer from their GitHub release page. Make sure to follow the instructions of the installer carefully, especially when prompted to modify your .zprofile to add Homebrew to your system’s PATH.

With Homebrew available, the required utilities can be installed by running

brew install cairo pkg-config

With all of this preparation out of the way, now it is time to actually install Algan itself!

uv pip install --extra-index-url https://test.pypi.org/simple/ algan --index-strategy unsafe-best-match

Linux requires some additional dependencies to build ManimPango (and potentially pycairo) from source. More specifically, this includes:

  • A C compiler,

  • Python’s development headers,

  • the pkg-config tool,

  • Pango and its development headers,

  • and Cairo and its development headers.

Instructions for popular systems / package managers are given below.

sudo apt update
sudo apt install build-essential python3-dev libcairo2-dev libpango1.0-dev

sudo dnf install python3-devel pkg-config cairo-devel pango-devel

sudo pacman -Syu base-devel cairo pango

As soon as the required dependencies are installed, you can run

uv pip install --extra-index-url https://test.pypi.org/simple/ algan --index-strategy unsafe-best-match

If you completed the installation instructions with no errors, then you are ready to Alganimate!

At this point, you can also open your project folder with the IDE of your choice. All modern Python IDEs (for example VS Code with the Python extension, or PyCharm) should automatically detect the local environment created by uv such that if you put

import algan

into a new file my-first-animation.py, the import is resolved correctly and autocompletion is available.

Happy Alganimating!