.. _installation-guide:

=======================
Sage Installation Guide
=======================

This is the installation guide for SageMath, a free open-source mathematics software system.
It is designed to help you install SageMath on your computer.
For options to run SageMath in the cloud, see the section :ref:`sec-cloud` below.

If you are planning to do development on SageMath, please refer instead to the
`Sage Developer's Guide <../developer/walkthrough.html>`_ for instructions on
obtaining the source code and building SageMath.

Local installation options
==========================

Depending on your operating system, various installation options are available. Select from the
options below to find instructions for your operating system.

.. tab:: Linux

  .. tab:: Conda

    To install SageMath from
    the `conda-forge <https://conda-forge.org/>`_ project
    you can use the following command:

    .. code-block:: console

      $ conda create -n sage sage python=3.13

    This will create a new conda environment named ``sage``
    containing SageMath and Python 3.13.
    You can then activate this environment with the command
    ``conda activate sage`` and start SageMath by typing ``sage``.
    
    For more details, see section :ref:`sec-installation-conda`.

  .. tab:: Arch Linux/Manjaro

    Install SageMath by running the following command in a terminal::

      $ sudo pacman -S sagemath
  
  .. tab:: Void Linux
  
    Install SageMath by running the following command in a terminal::

      $ xbps-install -S sagemath

  .. tab:: Nix

    Install SageMath by running the following command in a terminal::

      $ nix-env -iA nixpkgs.sage

  .. tab:: Gentoo

    Install SageMath from the `sage-on-gentoo <https://github.com/cschwan/sage-on-gentoo>`_
    overlay by running the following command in a terminal::

      $ emerge --noreplace eselect-repository && eselect repository enable sage-on-gentoo && emerge --sync
      $ emerge -av sage

  .. tab:: Other Linux distributions

    Not all Linux distributions provide an up-to-date binary package of SageMath.
    **Do not install a version of Sage older than 9.5.**
    Instead we recommend to install SageMath via Conda, as described in the
    corresponding section.

    If you are on an older version of your distribution and a recent
    version of SageMath is only available on a newer version of the
    distribution, consider upgrading your distribution.

    Alternatively, the 3-manifolds project provides a `SageMath AppImage <https://github.com/3-manifolds/sage_appimage>`_.
    It provides a self-contained binary distribution of SageMath that should be able to run on a wide variety of Linux
    systems. Beware that it is not packaged with Cython, so building certain sagemath programs or installing certain
    optional packages is not possible.

.. tab:: macOS 

  - Install the `binary build of SageMath <https://github.com/3-manifolds/Sage_macOS/releases>`_
    from the 3-manifolds project.  It is a signed and notarized app, which
    works for macOS 10.12 and newer. It is completely self-contained and
    provides the standard Sage distribution together with many optional
    packages. Additional optional Python packages can be installed with the
    ``%pip`` magic command and will go into your ``~/.sage`` directory.

  - Alternatively, install SageMath from the `conda-forge
    <https://conda-forge.org/>`_ project, as described in section
    :ref:`sec-installation-conda`.

.. tab:: Windows

    Enable `Windows Subsystem for Linux (WSL)
    <https://learn.microsoft.com/en-us/windows/wsl/>`_ and install
    Ubuntu as follows.

    - Make sure that hardware-assisted virtualization is enabled in
      the EFI or BIOS of your system. If in doubt, refer to your
      system's documentation for instructions on how to do this.

    - `Run the WSL install command as administrator.
      <https://learn.microsoft.com/en-us/windows/wsl/setup/environment#get-started>`_
      This will install Ubuntu Linux.

      Note that the basic instructions in the linked article apply to
      up-to-date installations of Windows 10 and 11, but there are
      also links to the procedures for older builds of Windows 10.

    - If you had installed WSL previously or installed it using
      different instructions, `verify that you are running WSL 2
      <https://learn.microsoft.com/en-us/windows/wsl/install#check-which-version-of-wsl-you-are-running>`_.

    - `Set up your Linux username and password.
      <https://learn.microsoft.com/en-us/windows/wsl/setup/environment#set-up-your-linux-username-and-password>`_
      Do not include any spaces in your username.

    - If your computer has less than 8GB of RAM, `change the WSL settings
      <https://learn.microsoft.com/en-us/windows/wsl/wsl-config#main-wsl-settings>`_
      to make at least 4GB of RAM available to WSL.

    Start Ubuntu from the Start menu, and type the following commands
    to install Sage from conda-forge. The second step will ask a few questions,
    and you may need to hit :kbd:`Enter` to confirm or type ``yes``
    and then hit :kbd:`Enter`.

    .. code-block:: console

      $ curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
      $ bash Miniforge3-$(uname)-$(uname -m).sh

    At the end of the installer run, you should see a message about adding certain commands in `~/.bashrc`.
    Now, either run the following command, or restart your WSL terminal.

    .. code-block:: console

      $ source ~/.bashrc

    You will see a different prompt in your terminal now, having `base` in it. Now, run

    .. code-block:: console

      $ conda create -n sage sage python=3.12

    (If there are any installation failures, please report them to
    the conda-forge maintainers by opening a `GitHub Issue for
    conda-forge/sage-feedstock <https://github.com/conda-forge/sage-feedstock/issues>`_.)

    You can now start SageMath as follows:

    .. code-block:: console

      $ conda activate sage
      $ sage


After installation, you can start SageMath in a terminal as follows:

.. code-block:: console

  $ sage

This way of starting Sage gives you the most basic way of using
Sage in the terminal. See :ref:`sec-launching` for recommended next steps,
in particular for setting up the Jupyter notebook, which is required if
you want to use graphics.

.. _sec-cloud:

In the cloud
============

- `Sage Binder repo <https://github.com/sagemath/sage-binder-env>`_ provides a
  Binder badge to launch JupyterLab environment with Sage.

- `Sage Cell Server <https://sagecell.sagemath.org/>`_ is a free online service for
  quick computations with Sage.

- `CoCalc <https://cocalc.com/>`_ is an online commercial service that provides Sage and
  many other tools.

- `Docker image sagemathinc/cocalc
  <https://hub.docker.com/r/sagemathinc/cocalc>`_ can be used on any system with Docker to run CoCalc locally.


More information
================

.. toctree::
   :maxdepth: 2

   conda
   source
   source-distro
   launching
   troubles
