Ways to use Macaulay2

To use Macaulay 2, you have a few options.

Use Online (Recommended for first time users)

Start Macaulay2 in your browser with no installation required. This is the quickest way to try examples, follow a workshop, or check whether M2 fits your needs.

Install Locally

Install Macaulay2 on your own computer for regular use, offline work, and access to your local files. This is the best option once you know you will use M2 often.

GitHub Codespaces

Run Macaulay2 in a ready-to-use cloud development environment through GitHub. Codespaces is helpful when local installation is difficult or when you want a consistent setup across machines.

Help

If you have tried everything and you couldn't get Macaulay2 to work, please head to the community section where you can find some resources to help you troubleshoot issues, find help, and receive feedback. On top of this, we have also included some helpful links at the bottom of each installation guide for each operating system that you can explore. Asking an AI model for help is also a good option for help and guidance.

Installation

If you have decided to install Macaulay2 locally, we have included detailed installation instructions for each major operating system (MacOS, Windows, and Linux) below. Should you encounter difficulties during this process, you can either ask for help from our amazing community, use it online or in a codespace (instructions below).

MacOS

Find the terminal

Open Spotlight Search with Cmd + Spacebar, then search for Terminal. Click the Terminal app in the search results, and a terminal window should open.

Install Homebrew

Go to the Homebrew website, then return to the terminal you opened in the previous step. Enter the install command shown on the Homebrew site; it currently looks like this:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Press return to run it. Homebrew will probably ask for your password; type it and press return again. No characters will appear while you type your password, which is normal. The command may change, so always verify the current command on the Homebrew website.

Add Homebrew to PATH

After installation, Homebrew will likely print commands for adding Homebrew to your PATH so your Mac knows where the software lives. These commands can be different for each user, so copy the commands shown in your own terminal, paste them in, and press return.

To confirm Homebrew is available, run:

brew help

If you see help output with sections like example usage, troubleshooting, contributing, and further help, you are ready to continue.

Install Macaulay2

In the terminal, run the following command to install Macaulay2. This might take a few minutes.

brew install Macaulay2/tap/M2

If the command has changed or does not work, refer to the Macaulay2 Homebrew tap or the Macaulay2 download page.

To confirm the installation, run:

M2

If you see output like this, you are good to go:

Macaulay2, version x.xx.xx
Type "help" to see useful commands

i1 :

Helpful links

Windows

Open PowerShell as Administrator

On Windows, Macaulay2 is easiest to install through Windows Subsystem for Linux using Ubuntu. Open the Start menu, search for PowerShell, right-click it, and choose Run as administrator.

Install WSL

In the administrator PowerShell window, run:

wsl --install

Restart your computer if Windows asks you to. This command normally enables WSL and installs Ubuntu by default. If the command is unavailable or fails because WSL is missing, install the latest WSL package from Microsoft's WSL releases page, then try the command again.

Install or Launch Ubuntu

If Ubuntu was not installed by the previous command, run this from PowerShell:

wsl --install -d Ubuntu

You can also install Ubuntu from the Microsoft Store by searching for Ubuntu and choosing an LTS release. Launch Ubuntu from the Start menu, wait for it to finish setting up, and create the Linux username and password it asks for.

Install Macaulay2 in Ubuntu

These commands go in the Ubuntu terminal, not in PowerShell. Add the stable Macaulay2 Ubuntu PPA, update package lists, and install Macaulay2:

sudo apt update
sudo add-apt-repository ppa:macaulay2/macaulay2
sudo apt update
sudo apt install macaulay2

If Ubuntu says add-apt-repository is not found, run sudo apt install software-properties-common, then repeat the PPA command. The older ppa:profzoom/macaulay2 PPA is for development builds, so use the stable PPA above unless you specifically want a development version.

Confirm the Windows Setup

Still inside Ubuntu, run:

M2

If you see the Macaulay2 welcome text and an i1 : prompt, the installation worked. Type exit to leave Macaulay2, and type exit again to close the Ubuntu shell.

Helpful links

Linux

Open a Linux Terminal

On Linux, you do not need WSL. Open your normal terminal application and use the commands for your distribution. Ubuntu and Debian-based systems use apt, while Fedora and similar systems use dnf.

Install on Ubuntu

For supported Ubuntu releases, the Macaulay2 project recommends adding the stable Macaulay2 PPA and installing with apt:

sudo apt update
sudo add-apt-repository ppa:macaulay2/macaulay2
sudo apt update
sudo apt install macaulay2

If add-apt-repository is missing, install it with sudo apt install software-properties-common, then rerun the PPA command.

Install on Debian

On Debian, Macaulay2 is available through apt, though stable Debian may provide an older version. Start with:

sudo apt update
sudo apt install macaulay2

For newer packages on Debian stable, follow the Debian-specific repository instructions on the Macaulay2 Linux installation wiki, since the repository file depends on your Debian release.

Install on Fedora or RHEL-compatible Linux

Fedora users can install Macaulay2 with dnf:

sudo dnf install Macaulay2

For the latest Fedora packages, or for Red Hat Enterprise Linux and compatible distributions such as Rocky Linux or AlmaLinux, use the repository instructions from the Macaulay2 Linux installation wiki before running the dnf install command.

Confirm the Linux Setup

After installation, start Macaulay2 from your Linux terminal:

M2

If you see the Macaulay2 welcome text and an i1 : prompt, the installation worked. Type exit to leave Macaulay2.

Helpful links

Codespaces

Using a codespace on GitHub is a nice alternative that allows you to use Macaulay2 if you don't want to install it locally or are facing trouble with the installation processes above.

Open the Macaulay2 repository

You need a free GitHub account and should be logged into GitHub before starting. Open the official Macaulay2 source repository in your browser.

Create the Codespace

Near the top-right of the file list, click the green <> Code button. In the dropdown, switch to the Codespaces tab, then click Create codespace on stable (or the latest stable version of Macaulay 2) or the + icon.

If you plan to modify Macaulay2 source code and keep your changes permanently, fork the repository first and create the Codespace from your fork.

Wait for initialization

A new browser tab will open with a web-based Visual Studio Code window. Wait for the container setup to finish; this can take a few minutes because the environment downloads dependencies and prepares a Linux container.

You are ready when the terminal stops printing setup logs and shows a normal prompt such as @codespace:/workspaces/M2$.

Run the Macaulay2 shell

Open the integrated terminal if it is not already visible by choosing Terminal > New Terminal. You can also use Ctrl + ` on Windows or Linux, or Cmd + ` on Mac.

Run:

M2

You should see the Macaulay2 welcome message and an interactive prompt like this:

i1 :

If M2 returns command not found, the latest source checkout may need to be built first. Run make in the repository terminal, wait for it to finish, then try M2 again.

Install the VS Code extension

For a better editing experience, install the Macaulay2 VS Code extension inside the Codespace. Click the Extensions icon in the left sidebar, search for Macaulay2, and click Install.

The extension adds useful editor features such as syntax highlighting, auto-completion, and tools for sending code from a file to an interactive Macaulay2 session.

Write your first script

In the file explorer, click the New File icon and create a file named hello.m2. Add a small Macaulay2 example:

R = QQ[x, y, z]
f = (x+y+z)^3

You can run the file using the extension, or from the active M2 prompt with:

load "hello.m2"

GitHub Codespaces saves your environment automatically. To return later, go to github.com/codespaces and reopen your active Macaulay2 Codespace. Note that free GitHub accounts receive 60 free hours of active codespaces per month. Once you reach that limit, you will be billed according to GitHub's codespace pricing.

Helpful links

Macaulay2 Codespace Tutorial