Installing SnapPy

Here are detailed instructions on how to get SnapPy working on a variety of platforms. The current version is 3.2 which was released on January 2025. If you encounter any problems installing SnapPy, please let us know.

macOS

Simply download SnapPy.dmg and copy SnapPy.app to the Applications folder. Double-click to start it, just like any other application. The current version works with macOS 10.14 and newer and earlier releases can be found here.

Windows

Simply download and run InstallSnapPy.exe. Earlier releases can be found here.

Linux app

Starting with SnapPy 3.2, a completely self-contained SnapPy AppImage is available that should work on any Linux system from the last 5 years. This AppImage contains its own private copy of Python, so if you plan to use SnapPy in your own Python programs, skip ahead to Python Modules for Linux. Here is the recipe for installing the AppImage in ~/bin after you have downloaded the file SnapPy-x86_64.AppImage:

mkdir -p ~/bin
mv ~/Downloads/SnapPy-x86_64.AppImage ~/bin
chmod +x ~/bin/SnapPy-x86_64.AppImage
ln -s -f ~/bin/SnapPy-x86_64.AppImage ~/bin/SnapPy
~/bin/SnapPy-x86_64.AppImage --install

The last command registers the SnapPy app with your desktop system and starts it. Next time, you can start SnapPy by using the desktop search tool with GNOME or the main menu with KDE. You can pin also the icon to your dash or task bar for easy access. From a terminal window, you can also start the app by typing SnapPy provided ~/bin is in your $PATH.

Python Modules for macOS or Windows

If you write Python programs on macOS or Windows, you may wish to install SnapPy as a Python module into your own copy of Python. We support Python 3.9 and up. (On macOS, use a Python downloaded from Python.org and not the one provided by Apple.) After installing Python, you may install a SnapPy module from your Terminal application or Command Prompt with the command:

python3 -m pip install --upgrade --user snappy snappy_15_knots

If you do not want the larger version of HTLinkExteriors that includes the 15 crossing knots (it uses 110M of disk space), omit snappy_15_knots from the command.

Python Modules for Linux

You can also use SnapPy with your Linux system’s version of Python, for example if you want to incorporate SnapPy in your own Python scripts. These instructions assume you have system administrator (superuser) privileges to install software packages from your Linux distribution. (If you’re not a superuser, use either the Linux app or conda.)

The first step is to install Python and other requirements; here’s how to do that on the most popular Linux distributions:

  • Ubuntu/Debian/Mint/MX Linux/Elementary: Tested on Ubuntu 24.04:

    sudo apt install python3-pip python3-tk

  • Fedora: Tested on Fedora 41:

    sudo dnf install python3-pip python3-tkinter

  • Arch/Manjaro/EndeavourOS: Install via:

    sudo pacman -Sy python-pip tk

  • openSUSE: For Tumbleweed:

    sudo zypper install python3-pip python3-tk

    For Leap, as of version 15.6 you need to ask for a recent version of Python or it will give you Python 3.6 which is too old for SnapPy:

    sudo zypper install python312-pip python312-tk

    You will need to replace python3 by python3.12 in subsequent steps.

  • Red Hat Enterprise Linux/CentOS/Rocky Linux/AlmaLinux:: These instructions are for version 8 or later; tested on AlmaLinux 8 and 9:

    sudo dnf install python3.11-pip python3.11-tkinter

    You will also need to replace python3 by python3.11 in subsequent steps.

Next, you need to install the SnapPy Python modules. For this, you can either use a virtual environment (python -m venv) or do a user install (pip install --user). The former will work on any version of Linux, whereas the latter is now strongly discouraged on many systems (e.g. Ubuntu 24.04). If you have not previously installed SnapPy on this computer, we recommend using a virtual environment, but suggest a user install if you are upgrading an existing version of SnapPy that was installed in that manner.

Virtual environment

Here is the official tutorial on using virtual environments in Python and an in-depth article. A recipe is:

python3 -m venv snappy_venv
# Switch to snappy_venv's Python
source snappy_venv/bin/activate
pip install snappy snappy_15_knots
# Start the SnapPy app!
SnapPy
# Return to system Python
deactivate

If you always want to use the snappy_venv Python, adjust your $PATH to start with snappy_venv/bin.

User install

To do a user install with pip, try:

# Note no "sudo" below!
python3 -m pip install --upgrade --user snappy snappy_15_knots

If you get a long error message that starts:

error: externally-managed-environment

you should probably use a virtual environment; however, you can force pip to do a user install via:

# Note no "sudo" below!
python3 -m pip install --upgrade --user --break-system-packages snappy snappy_15_knots

Despite the scary name, provided you don’t use sudo, this will not actually modify the system packages, but rather install snappy into the subdirectory ~/.local/share/python3.*/site-packages of your home directory.

After a user install, you run the following command to start the app:

~/.local/bin/SnapPy

So that you can start SnapPy with just the command SnapPy, make sure ~/.local/bin is in in your path.

SageMath

SnapPy has some special features when used within SageMath, the universal mathematics software based on Python. This section describes how to install SnapPy into your existing copy of SageMath:

sage -pip install --upgrade snappy snappy_15_knots

Alternatively, SageMath on CoCalc (formerly the SageMathCloud) also has SnapPy preinstalled, and the graphics features even work via the X11 interface, see the bottom of that page for more.

The graphical features may or may not work, depending on how Tkinter was configured within Sage. (There is no problem on macOS if you use this SageMath binary.) If the graphical features seem to “hang” when you try to start them, type %gui tk at the Sage prompt; please note that doing so may break Sage’s “attach” feature.

Kitchen sink

SnapPy gains extra features when used in SageMath and one can use Sage’s Python to interact not just with SnapPy but a range of other computational tools in low-dimensional topology including Regina, snap, heegaard, gridlink, and flipper. We offer a prepackaged Docker image with all of the above tools and many more; using this is sometimes the easiest way to get a working setup for such multifaceted computations, especially on Windows. For more, watch this demonstration.

Conda

Conda can be used to install Python on all platforms and is a particularly good choice to use SnapPy on the older Linux systems often found on high-performance clusters. Here is a recipe for installing SnapPy into a new conda environment on macOS or Linux:

source ~/miniforge3/bin/activate
mamba create --name snappy_env python=3.12
conda activate snappy_env
pip install snappy
python -m snappy.app

Source code

The complete source code for all platforms: snappy-3.2.tar.gz

You can also browse our source code repository or clone it using git via:

git clone https://github.com/3-manifolds/SnapPy.git