Installing sage-flatsurf

There are several different ways to install sage-flatsurf on your machine. You can

If you are having trouble with this or are on another operating system, please contact us. We’re thrilled about any new user of sage-flatsurf and we’re very happy to help and in the process improve these installation instructions.

Install with the pixi tarball

Open a terminal and run the following command:

curl -fsSL https://github.com/flatsurf/sage-flatsurf/releases/download/0.6.1/sage-flatsurf-0.6.1.unix.tar.gz | tar zxf -

This will download the latest pixi tarball from our Releases Page and extract it into a subdirectory of the directory where you opened the terminal.

Due to conda limitations [1], this only works if the current directory does not contain any spaces. Run \(pwd\) to double check that your absolute path is free of whitespace.

The entire installation of sage-flatsurf and its dependencies are going to reside in this subdirectory. This is not making any changes to your system. If you later change your mind, you can safely delete that directory, or move or rename it.

You can now use sage-flatsurf in a terminal or through Jupyter notebooks. To launch sage-flatsurf in the terminal, run:

./sage-flatsurf-0.6.1/sage

To launch a browser with Jupyter Lab instead, run:

./sage-flatsurf-0.6.1/jupyterlab

The first time you run either of these commands, the installer downloads a copy of SageMath and some other dependencies (in total this is going to use about 7GB of disk space.) In particular on macOS this can take a very long time on the first launch (probably due to security measures in the operating system), please be patient.

When a new version of sage-flatsurf is released and you want to upgrade, just download the latest tarball and extract it elsewhere. The two installations do not interfere with each other and you can just delete the old version if you do not need it anymore.

There is also a “nightly” build of sage-flatsurf that contains the latest development version. To download it, go to the latest installer workflow run select \(unix\) or \(windows\) and find the file in the section “Provide installer as a build artifact”. (You need to be logged in at GitHub for this to work.)

Install with the Windows Installer

Download the latest .exe file from the Releases Page and execute it normally. The installer is going to configure your system to be able to run Windows Subsystem for Linux. It is going to ask for administrator privileges to install the necessary dependencies on your system and a reboot might be required during the installation process.

Upon first launch of sage-flatsurf from your Start menu, a virtual machine running Ubuntu is created in your \(%LOCALAPPDATA%\). This machine won’t interfere with any other WSL machines you might have set up on your system.

This Ubuntu system is then going to download all the dependencies of sage-flatsurf (about 7GB once extracted.) The first time, this might take some time, please be patient.

To remove sage-flatsurf again, please use the provided “Uninstall Virtual Machine” link from your Start menu, or just delete the sage-flatsurf directory from \(%LOCALAPPDATA\).

When a new version of sage-flatsurf is released and you want to upgrade, just download the latest installer and run it. The two versions of sage-flatsurf do not interfere with each other. If you do not need the old version of sage-flatsurf anymore, just uninstall it.

Install with Mamba

Almost the entire flatsurf stack is available at conda-forge.

If you already have mambaforge installed, you can create an environment with the entire flatsurf stack by running:

mamba create -n flatsurf sage-flatsurf pyflatsurf pyexactreal sage pip

Some optional bits of the flatsurf stack are only available on PyPI, to install them as well run:

mamba activate flatsurf
pip install ipyvue-flatsurf flipper realalg veerer

Install into SageMath

If you are using a source build of SageMath or if you downloaded a SageMath binary, you can install sage-flatsurf into SageMath. Note that this does not install all the optional dependencies of sage-flatsurf so some computations might fail in this setup:

sage -pip install sage-flatsurf

To uninstall sage-flatsurf again later:

sage -pip uninstall sage-flatsurf

Install from PyPI

You can install sage-flatsurf from PyPI if you installed sagelib as a Python package. Again, this does not come with the optional dependencies of sage-flatsurf, so some computations might fail in this setup:

pip install --user sage-flatsurf

To uninstall sage-flatsurf again later:

pip uninstall --user sage-flatsurf