Table of contents
Some familiarity with the use of the Unix command line may be required to build Sage from the source code.
Building Sage from the source code has the major advantage that your install will be optimized for your particular computer and should therefore offer better performance and compatibility than a binary install.
Moreover, it offers you full development capabilities: you can change absolutely any part of Sage or the programs on which it depends, and recompile the modified parts.
See the file README.md
SAGE_ROOT for information on supported platforms and
The following sections provide some additional details. Most users will not need to read them.
This section details the technical prerequisites needed on all platforms. See also the System-specific requirements below.
Disk space and memory¶
Your computer comes with at least 6 GB of free disk space. It is recommended to have at least 2 GB of RAM, but you might get away with less (be sure to have some swap space in this case).
A C/C++ compiler: Since SageMath builds its own GCC if needed, a wide variety of C/C++ compilers is supported. Many GCC versions work, from as old as version 4.8 (but we recommend at least 5.1) to the most recent release. Clang also works. See also Using alternative compilers.
make: GNU make, version 3.80 or later. Version 3.82 or later is recommended.
m4: GNU m4 1.4.2 or later (non-GNU or older versions might also work).
perl: version 5.8.0 or later.
ar and ranlib: can be obtained as part of GNU binutils.
tar: GNU tar version 1.17 or later, or BSD tar.
python: Python 3.4 or later, or Python 2.7. (This range of versions is a minimal requirement for internal purposes of the SageMath build system, which is referred to as
Other versions of these may work, but they are untested.
Fortran and compiler suites¶
Sage installation also needs a Fortran compiler. It is determined
automatically whether Sage’s GCC package, or just its part containing
gfortran needs to be installed. This can be
overwritten by running
./configure with option
Officially we support gfortran from GNU Compiler Collection (GCC). If C and C++ compilers also come from there (i.e., gcc and g++), their versions should match. Alternatively, one may use C and C++ compilers from Clang: a C language family frontend for LLVM, and thus matching versions of clang, clang++ , along with a recent gfortran. (Flang (or other LLVM-based Fortran compilers) are not officially supported, however it is possible to to build Sage using flang, with some extra efforts needed to set various flags; this is work in progress at the moment (May 2019)).
Therefore, if you plan on using your own GCC compilers, then make sure that their versions match.
To force using specific compilers, set environment variables
FC (for C, C++, and Fortran compilers, respectively)
to the desired values, and run
./configure. For example,
./configure CC=clang CXX=clang++ FC=gfortran will configure Sage
to be built with Clang C/C++ compilers and Fortran compiler
Alternatively, Sage includes a GCC package, so that C, C++ and Fortran compilers will be built when the build system detects that it is needed, e.g., non-GCC compilers, or versions of the GCC compilers known to miscompile some components of Sage, or simply a missing Fortran compiler. In any case, you always need at least a C/C++ compiler to build the GCC package and its prerequisites before the compilers it provides can be used.
Note that you can always override this behavior through the configure
Using alternative compilers.
There are some known problems with old assemblers, in particular when
fflas_ffpack packages. You should ensure
that your assembler understands all instructions for your
processor. On Linux, this means you need a recent version of
binutils; on macOS you need a recent version of Xcode.
Python for venv¶
By default, Sage will try to use system’s \(python3\) to set up a virtual
environment, a.k.a. venv
rather than building a Python 3 installation from scratch.
--without-system-python3 in case you want Python 3
built from scratch.
Sage will accept versions 3.7.x to 3.10.x.
You can also use
--with-python=/path/to/python3_binary to tell Sage to use
/path/to/python3_binary to set up the venv. Note that setting up venv requires
a number of Python modules to be available within the Python in question. Currently,
for Sage 9.6, these modules are as follows:
they will be checked for by the
After extracting the Sage source tarball, the subdirectory
contains the source distributions for everything on which Sage depends.
If cloned from a git repository, the upstream tarballs will be downloaded, verified, and cached as part of the Sage installation process. We emphasize that all of this software is included with Sage, so you do not have to worry about trying to download and install any one of these packages (such as Python, for example) yourself.
When the Sage installation program is run, it will check that you have each of the above-listed prerequisites, and inform you of any that are missing, or have unsuitable versions.
On macOS, there are various developer tools needed which may require some registration on Apple’s developer site; see macOS prerequisite installation.
On Redhat-derived systems not all perl components are installed by
default and you might have to install the
On Cygwin, the
liblapack-devel packages are required.
To check if you have the above prerequisites installed, for example
$ command -v perl
$ which perl
on the command line. If it gives an error (or returns nothing), then
perl is not installed, or it is installed but not in your
Linux recommended installation¶
On Linux systems (e.g., Ubuntu, Redhat, etc),
ranlib are in the
The other programs are usually located in packages with their respective names.
Assuming you have sufficient privileges, you can install the
other necessary/standard components. The lists provided below are longer than
the minimal prerequisites, which are basically
tar, but there is no real need to build compilers and other standard tools
and libraries on a modern Linux system, in order to be able to build Sage.
If you do not have the privileges to do this, ask your system administrator to
do this, or build the components from source code.
The method of installing additional software varies from distribution to
distribution, but on a Debian based system (e.g.
Ubuntu or Mint),
you would use
On Debian (“buster” or newer) or Ubuntu (“bionic” or newer):
$ sudo apt-get install bc binutils bzip2 ca-certificates cliquer cmake curl ecl eclib-tools fflas-ffpack flintqs g++ gcc gengetopt gfan gfortran glpk-utils gmp-ecm lcalc libatomic-ops-dev libboost-dev libbraiding-dev libbrial-dev libbrial-groebner-dev libbz2-dev libcdd-dev libcdd-tools libcliquer-dev libcurl4-openssl-dev libec-dev libecm-dev libffi-dev libflint-arb-dev libflint-dev libfplll-dev libfreetype6-dev libgc-dev libgd-dev libgf2x-dev libgiac-dev libgivaro-dev libglpk-dev libgmp-dev libgsl-dev libhomfly-dev libiml-dev liblfunction-dev liblinbox-dev liblrcalc-dev liblzma-dev libm4ri-dev libm4rie-dev libmpc-dev libmpfi-dev libmpfr-dev libncurses5-dev libntl-dev libopenblas-dev libpari-dev libpcre3-dev libplanarity-dev libppl-dev libprimesieve-dev libpython3-dev libqhull-dev libreadline-dev librw-dev libsingular4-dev libsqlite3-dev libssl-dev libsuitesparse-dev libsymmetrica2-dev libz-dev libzmq3-dev libzn-poly-dev m4 make nauty openssl palp pari-doc pari-elldata pari-galdata pari-galpol pari-gp2c pari-seadata patch perl pkg-config planarity ppl-dev python3 python3-distutils r-base-dev r-cran-lattice singular singular-doc sqlite3 sympow tachyon tar tox xcas xz-utils
On Fedora / Redhat / CentOS:
$ sudo yum install --setopt=tsflags= L-function L-function-devel R R-devel Singular Singular-devel arb arb-devel binutils boost-devel brial brial-devel bzip2 bzip2-devel cddlib cliquer cliquer-devel cmake curl diffutils ecl eclib eclib-devel fflas-ffpack-devel findutils flint flint-devel gc gc-devel gcc gcc-c++ gcc-gfortran gd gd-devel gengetopt gf2x gf2x-devel gfan giac giac-devel givaro givaro-devel glpk glpk-devel glpk-utils gmp gmp-devel gmp-ecm gmp-ecm-devel gsl gsl-devel iml iml-devel libatomic_ops libatomic_ops-devel libbraiding libcurl-devel libffi libffi-devel libfplll libfplll-devel libhomfly-devel libmpc libmpc-devel linbox lrcalc-devel m4 m4ri-devel m4rie-devel make mpfr-devel nauty ncurses-devel ntl-devel openblas-devel openssl openssl-devel palp pari-devel pari-elldata pari-galdata pari-galpol pari-gp pari-seadata patch pcre pcre-devel perl perl-ExtUtils-MakeMaker perl-IPC-Cmd pkg-config planarity planarity-devel ppl ppl-devel primecount primecount-devel primesieve primesieve-devel python3 python3-devel qhull qhull-devel readline-devel rw-devel sqlite sqlite-devel suitesparse suitesparse-devel symmetrica-devel sympow tachyon tachyon-devel tar tox which xz xz-devel zeromq zeromq-devel zlib-devel zn_poly zn_poly-devel
On Arch Linux:
$ sudo pacman -S arb bc binutils boost brial cblas cddlib cmake ecl eclib fflas-ffpack flintqs gc gcc gcc-fortran gd gf2x gfan giac glpk gsl iml lapack lcalc libatomic_ops libbraiding libgiac libhomfly linbox lrcalc m4 m4ri m4rie make nauty openblas openssl palp pari pari-elldata pari-galdata pari-galpol pari-seadata patch perl planarity ppl primecount primesieve python qhull r rankwidth readline singular sqlite3 suitesparse symmetrica sympow tachyon tar which zn_poly
In addition to these, if you don’t want Sage to build optional packages that might be available from your OS, cf. the growing list of such packages on trac ticket #27330, install on Debian (“buster” or newer) or Ubuntu (“bionic” or newer):
$ sudo apt-get install 4ti2 clang coinor-cbc coinor-libcbc-dev graphviz libfile-slurp-perl libgraphviz-dev libigraph-dev libisl-dev libjson-perl libmongodb-perl libnauty-dev libperl-dev libpolymake-dev libsvg-perl libterm-readkey-perl libterm-readline-gnu-perl libxml-libxslt-perl libxml-writer-perl libxml2-dev lrslib ninja-build pari-gp2c pdf2svg polymake texinfo
On Fedora / Redhat / CentOS:
$ sudo yum install 4ti2 clang coin-or-Cbc coin-or-Cbc-devel coxeter coxeter-devel coxeter-tools graphviz igraph igraph-devel isl-devel libnauty-devel libxml2-devel lrslib ninja-build pari-galpol pari-seadata pdf2svg perl-ExtUtils-Embed perl-File-Slurp perl-JSON perl-MongoDB perl-Term-ReadLine-Gnu perl-TermReadKey perl-XML-LibXML perl-XML-LibXSLT perl-XML-Writer polymake texinfo
On Arch Linux:
$ sudo pacman -S 4ti2 clang coin-or-cbc coxeter graphviz igraph libxml2 lrs ninja pari-elldata pari-galpol pari-seadata pdf2svg perl-term-readline-gnu polymake
macOS prerequisite installation¶
On macOS systems, you need a recent version of Command Line Tools. It provides all the above requirements.
Run the command
xcode-select --install from a Terminal window and click “Install”
in the pop-up dialog box.
If you have already installed Xcode (which at the time of writing is freely available in the Mac App Store, or through https://developer.apple.com/downloads/ provided you registered for an Apple Developer account), you can install the command line tools from there as well.
If you have not installed Xcode you can get these tools as a relatively small download, but it does require a registration.
First, you will need to register as an Apple Developer at https://developer.apple.com/register/.
Having done so, you should be able to download it for free at https://developer.apple.com/downloads/index.action?=command%20line%20tools
Alternately, https://developer.apple.com/opensource/ should have a link to Command Line Tools.
macOS recommended installation¶
Although Sage can in theory build its own version of gfortran, this can take a while, and the process fails on some recent versions of OS X. So instead you can install your own copy. One advantage of this is that you can install it once, and it will get used every time you build Sage, rather than building gfortran every time.
One way to do that is with the Homebrew package manager. Install Homebrew as their web page describes, and then the command
$ brew install gcc
will install Homebrew’s gcc package, which includes gfortran. Sage will also use other Homebrew packages, if they are present. You can install the following:
$ brew install arb bdw-gc boost bzip2 cmake curl ecl flint fplll freetype gcc gd gengetopt gfortran glpk gmp gpatch gsl libatomic_ops libffi libiconv libmpc libpng mpfi mpfr nauty ncurses ntl openblas openssl pari pari-elldata pari-galdata pari-galpol pari-seadata pcre pkg-config ppl primesieve python3 qhull r readline singular sqlite suite-sparse tox xz zeromq zlib
Some Homebrew packages are installed “keg-only,” meaning that they are not available in standard paths. To make them accessible when building Sage, run
$ source SAGE_ROOT/.homebrew-build-env
SAGE_ROOT by Sage’s home directory). You can add a
command like this to your shell profile if you want the settings to
persist between shell sessions.
Some additional optional packages are taken care of by:
$ brew install apaffenholz/polymake/polymake cbc graphviz igraph isl libxml2 llvm nauty ninja pdf2svg texinfo
Cygwin prerequisite installation¶
Sage can be built only on the 64-bit version of Cygwin. See
the file README.md
SAGE_ROOT for the most up-to-date instructions for building Sage
Although it is possible to install Sage’s dependencies using the Cygwin
graphical installer, it is recommended to install the apt-cyg command-line package
installer, which is used for the remainder of these instructions. To
apt-cyg, you must have already installed (using the graphical
installer) the following packages at a minimum:
bzip2 coreutils gawk gzip tar wget
With the exception of
wget most of these are included in the default
package selection when you install Cygwin. Then, to install
$ curl -OL https://rawgit.com/transcode-open/apt-cyg/master/apt-cyg $ install apt-cyg /usr/local/bin $ rm -f apt-cyg
To install the current set of system packages known to work for building Sage, run:
$ apt-cyg install R binutils bzip2 cddlib-devel cddlib-tools cmake curl findutils gcc-core gcc-fortran gcc-g++ gengetopt glpk libatomic_ops-devel libboost-devel libbz2-devel libcrypt-devel libcurl-devel libffi-devel libflint-devel libfreetype-devel libgc-devel libgd-devel libglpk-devel libgmp-devel libgsl-devel libiconv-devel liblapack-devel liblzma-devel libmpc-devel libmpfr-devel libncurses-devel libntl-devel libopenblas libpcre-devel libreadline-devel libsqlite3-devel libssl-devel libsuitesparseconfig-devel libtirpc-devel libzmq-devel m4 make patch perl perl-ExtUtils-MakeMaker python39 python39-devel python39-urllib3 qhull singular singular-devel sqlite3 tar which xz zlib-devel
Optional packages that are also known to be installable via system packages include:
$ apt-cyg install clang graphviz info lib4ti2-devel lib4ti2_0 libisl-devel libxml2-devel ninja perl-Term-ReadLine-Gnu
Ubuntu on Windows Subsystem for Linux (WSL) prerequisite installation¶
Sage can be installed onto Linux running on Windows Subsystem for Linux (WSL). These instructions describe a fresh install of Ubuntu 20.10, but other distributions or installation methods should work too, though have not been tested.
Enable hardware-assisted virtualization in the EFI or BIOS of your system. Refer to your system (or motherboard) maker’s documentation for instructions on how to do this.
Set up WSL by following the official WSL setup guide. Be sure to do the steps to install WSL2 and set it as default.
Go to the Microsoft Store and install Ubuntu.
Start Ubuntu from the start menu. Update all packages to the latest version.
Reboot the all running WSL instances one of the following ways:
Open Windows Services and restart the LxssManager service.
Open the Command Prompt or Powershell and enter this command:
Upgrade to the Ubuntu 20.10. This step will not be necessary once Ubuntu 20.10 is available in the Microsoft Store.
From this point on, follow the instructions in the Linux recommended installation section.
It is strongly recommended to put the Sage source files in the Linux file system, for example, in the
/home/username/sage directory, and not in the Windows file system (e.g.
You may encounter permission errors of the kind
"[Errno 13] Permission denied: 'build/bdist.linux-x86_64/wheel/<package>.dist-info'" during
This usually comes from a permission conflict between the Windows and Linux file system.
To fix it create a temporary build folder in the Linux file system using
mkdir -p ~/tmp/sage and use it for building by
eval SAGE_BUILD_DIR="~/tmp/sage" make.
Also see the related Github issue for other workarounds.
When the installation is complete, you may be interested in WSL Post-installation steps.
On Solaris, you would use
pkgadd and on OpenSolaris
ipf to install
the necessary software.
On other systems, check the documentation for your particular operating system.
Notes on using conda¶
If you don’t want conda to be used by sage, deactivate conda (for the current shell session).
Type:$ conda deactivate
Repeat the command until
conda infoshows:$ conda info active environment : None ...
Then SageMath will be built either using the compilers provided by the operating system, or its own compilers.
Specific notes for
On macOS, the system-wide BSD
tar supplied will build Sage, so there is no
need to install the GNU
Using alternative compilers¶
Sage developers tend to use fairly recent versions of GCC. Nonetheless, the Sage build process on Linux should succeed with any reasonable C/C++ compiler; (we do not recommend GCC older than version 5.1). This is because Sage will build GCC first (if needed) and then use that newly built GCC to compile Sage.
If you don’t want this and want to try building Sage with a different set of
you need to pass Sage’s
./configure compiler names, via environment
FC, for C, C++, and Fortran compilers,
respectively, e.g. if you C compiler is
clang, your C++ compiler is
and your Fortran compiler is
flang then you would need to run:
$ CC=clang CXX=clang++ FC=flang ./configure
make. It is recommended that you inspect the output of
in order to check that Sage will not try to build GCC. Namely, there should be lines like:
gcc-7.2.0 will not be installed (configure check) ... gfortran-7.2.0 will not be installed (configure check)
indicating that Sage will not attempt to build
The following programs are recommended. They are not strictly required at build time or at run time, but provide additional capabilities:
LaTeX: highly recommended.
It is highly recommended that you have LaTeX installed, but it is not required. The most popular packaging is TeX Live, which can be installed following the directions on their web site. On Linux systems you can alternatively install your distribution’s texlive packages:
$ sudo apt-get install texlive # debian $ sudo yum install texlive # redhat
or similar commands. In addition to the base TeX Live install, you may need some optional TeX Live packages, for example country-specific babel packages for the localized Sage documentation.
If you don’t have either ImageMagick or ffmpeg, you won’t be able to view animations. ffmpeg can produce animations in more different formats than ImageMagick, and seems to be faster than ImageMagick when creating animated GIFs. Either ImageMagick or dvipng is used for displaying some LaTeX output in the Sage notebook.
On Debian/Ubuntu, the following system packages are recommended.
texlive-generic-extra(to generate pdf documentation)
texlive-xetex(to convert Jupyter notebooks to pdf)
latexmk(to generate pdf documentation)
pandoc(to convert Jupyter notebooks to pdf)
dvipng(to render text with LaTeX in Matplotlib)
default-jdk(to run the Jmol 3D viewer from the console and generate images for 3D plots in the documentation)
ffmpeg(to produce animations)
libavdevice-dev(to produce animations)
If you want to use Tcl/Tk libraries in Sage, you need to install the Tcl/Tk and its development headers before building Sage. Sage’s Python will then automatically recognize your system’s install of Tcl/Tk.
On Linux systems, these are usually provided by the tk and tk-dev (or tk-devel) packages which can be installed using:
$ sudo apt-get install tk tk-dev
or similar commands.
If you installed Sage first, all is not lost. You just need to rebuild Sage’s Python and any part of Sage relying on it:
$ sage -f python3 # rebuild Python3 $ make # rebuild components of Sage depending on Python
after installing the Tcl/Tk development libraries as above.
sage: import _tkinter sage: import Tkinter
does not raise an
ImportError, then it worked.
Follow the procedure in the file README.md in
Additional remarks: You do not need to be logged in as root, since no files are changed outside of the
sage-x.ydirectory. In fact, it is inadvisable to build Sage as root, as the root account should only be used when absolutely necessary and mistyped commands can have serious consequences if you are logged in as root.
makeperforms the usual steps for each Sage’s dependency, but installs all the resulting files into the local build tree. Depending on the age and the architecture of your system, it can take from a few tens of minutes to several hours to build Sage from source. On really slow hardware, it can even take a few days to build Sage.
Each component of Sage has its own build log, saved in
SAGE_ROOT/logs/pkgs. If the build of Sage fails, you will see a message mentioning which package(s) failed to build and the location of the log file for each failed package. If this happens, then paste the contents of these log file(s) to the Sage support newsgroup at https://groups.google.com/group/sage-support. If the log files are very large (and many are), then don’t paste the whole file, but make sure to include any error messages. It would also be helpful to include the type of operating system (Linux, macOS, Solaris, OpenSolaris, Cygwin, or any other system), the version and release date of that operating system and the version of the copy of Sage you are using. (There are no formal requirements for bug reports – just send them; we appreciate everything.)
To start Sage, you can now simply type from Sage’s home directory:
You should see the Sage prompt, which will look something like this:
$ sage ┌────────────────────────────────────────────────────────────────────┐ │ SageMath version 8.8, Release Date: 2019-06-26 │ │ Using Python 3.7.3. Type "help()" for help. │ └────────────────────────────────────────────────────────────────────┘ sage:
Note that Sage should take well under a minute when it starts for the first time, but can take several minutes if the file system is slow or busy. Since Sage opens a lot of files, it is preferable to install Sage on a fast filesystem if possible.
Just starting successfully tests that many of the components built correctly. Note that this should have been already automatically tested during the build process. If the above is not displayed (e.g., if you get a massive traceback), please report the problem, e.g., at https://groups.google.com/group/sage-support.
After Sage has started, try a simple command:
sage: 2 + 2 4
Or something slightly more complicated:
sage: factor(2005) 5 * 401
Optional, but highly recommended: Test the install by typing
./sage --testall. This runs most examples in the source code and makes sure that they run exactly as claimed. To test all examples, use
./sage --testall --optional=all --long; this will run examples that take a long time, and those that depend on optional packages and software, e.g., Mathematica or Magma. Some (optional) examples will therefore likely fail.
Alternatively, from within
$SAGE_ROOT, you can type
make ptest) to run all the standard test code serially (respectively in parallel).
Testing the Sage library can take from half an hour to several hours, depending on your hardware. On slow hardware building and testing Sage can even take several days!
Optional: Check the interfaces to any other software that you have available. Note that each interface calls its corresponding program by a particular name: Mathematica is invoked by calling
math, Maple by calling
maple, etc. The easiest way to change this name or perform other customizations is to create a redirection script in
$SAGE_ROOT/local/bin. Sage inserts this directory at the front of your
PATH, so your script may need to use an absolute path to avoid calling itself; also, your script should pass along all of its arguments. For example, a
maplescript might look like:
#!/bin/sh exec /etc/maple10.2/maple.tty "$@"
Optional: There are different possibilities to make using Sage a little easier:
Make a symbolic link from
/usr/local/bin/sage(or another directory in your
$ ln -s /path/to/sage-x.y/sage /usr/local/bin/sage
Now simply typing
sagefrom any directory should be sufficient to run Sage.
$SAGE_ROOT/sageto a location in your
PATH. If you do this, make sure you edit the line:
at the beginning of the copied
sagescript according to the direction given there to something like:
(note that you have to change
<SAGE_ROOT>above!). It is best to edit only the copy, not the original.
For KDE users, create a bash script called
sagecontaining the lines (note that you have to change
#!/usr/bin/env bash konsole -T "sage" -e <SAGE_ROOT>/sage
make it executable:
$ chmod a+x sage
and put it somewhere in your
You can also make a KDE desktop icon with this line as the command (under the Application tab of the Properties of the icon, which you get my right clicking the mouse on the icon).
On Linux and macOS systems, you can make an alias to
$SAGE_ROOT/sage. For example, put something similar to the following line in your
(Note that you have to change
<SAGE_ROOT>above!) Having done so, quit your terminal emulator and restart it. Now typing
sagewithin your terminal emulator should start Sage.
Optional: Install optional Sage packages and databases. Type
sage --optionalto see a list of them (this requires an Internet connection), or visit https://www.sagemath.org/packages/optional/. Then type
sage -i <package-name>to automatically download and install a given package.
Optional: Run the
install_scriptscommand from within Sage to create GAP, GP, Maxima, Singular, etc., scripts in your
install_scripts?in Sage for details.
Have fun! Discover some amazing conjectures!
Rebasing issues on Cygwin¶
Building on Cygwin will occasionally require “rebasing”
Sage provides some scripts, located in
$SAGE_LOCAL/bin, to do so:
sage-rebaseall.sh, a shell script which calls Cygwin’s
rebaseallprogram. It must be run within a
dashshell from the
SAGE_ROOTdirectory after all other Cygwin processes have been shut down and needs write-access to the system-wide rebase database located at
/etc/rebase.db.i386, which usually means administrator privileges. It updates the system-wide database and adds Sage dlls to it, so that subsequent calls to
rebaseallwill take them into account.
sage-rebase.sh, a shell script which calls Cygwin’s
rebaseprogram together with the
-O/--obliviousoption. It must be run within a shell from
SAGE_ROOTdirectory. Contrary to the
sage-rebaseall.shscript, it neither updates the system-wide database, nor adds Sage dlls to it. Therefore, subsequent calls to
rebaseallwill not take them into account.
sage-rebase.bat), an MS-DOS batch file which calls the
sage-rebase.sh) script. It must be run from a Windows command prompt, after adjusting
SAGE_ROOTto the Windows location of Sage’s home directory, and, if Cygwin is installed in a non-standard location, adjusting
Some systems may encounter this problem frequently enough to make building or
If executing the above scripts or directly calling
rebaseall does not solve
rebasing issues, deleting the system-wide database and then regenerating it
from scratch, e.g., by executing
sage-rebaseall.sh, might help.
Finally, on Cygwin, one should also avoid the following:
building in home directories of Windows domain users;
building in paths with capital letters (see trac ticket #13343, although there has been some success doing so).
To build Sage from scratch, you would typically execute
make in Sage’s home
directory to build Sage and its HTML
make command is pretty smart, so if your build of Sage is interrupted,
make again should cause it to pick up where it left off.
make command can also be given options, which control what is built and
how it is built:
make buildbuilds Sage: it compiles all of the Sage packages. It does not build the documentation.
make docbuilds Sage’s documentation in HTML format. Note that this requires that Sage be built first, so it will automatically run
make buildfirst. Thus, running
make docis equivalent to running
make doc-pdfbuilds Sage’s documentation in PDF format. This also requires that Sage be built first, so it will automatically run
make doc-html-no-plotbuilds Sage’s documentation in html format but skips the inclusion of graphics auto-generated using the
.. PLOTmarkup and the
sphinx_plotfunction. This is primarily intended for use when producing certain binary distributions of Sage, to lower the size of the distribution. As of this writing (December 2014, Sage 6.5), there are only a few such plots, adding about 4M to the
local/share/doc/sage/directory. In the future, this may grow, of course. Note: after using this, if you want to build the documentation and include the pictures, you should run
make doc-uninstall, because the presence, or lack, of pictures is cached in the documentation output. You can benefit from this no-plot feature with other make targets by doing
export SAGE_DOCBUILD_OPTS+=' --no-plot'
make ptestlong: these run Sage’s test suite. The first version skips tests that need more than a few seconds to complete and those which depend on optional packages or additional software. The second version includes the former, and so it takes longer. The “p” in
pteststands for “parallel”: tests are run in parallel. If you want to run tests serially, you can use
make testlonginstead. If you want to run tests depending on optional packages and additional software, you can use
make testalllong, or
make doc-cleaneach remove several directories which are produced when building the documentation.
make distcleanrestores the Sage directory to its state before doing any building: it is almost equivalent to deleting Sage’s entire home directory and unpacking the source tarfile again, the only difference being that the
.gitdirectory is preserved, so git branches are not deleted.
Sage uses several environment variables to control its build process.
Most users won’t need to set any of these: the build process just works on many
(Note though that setting
MAKE, as described below, can significantly
speed up the process.)
Building Sage involves building about 100 packages, each of which has its own
The Sage source tarball already includes the sources for all standard
packages, that is, it allows you to build Sage without internet
connection. The git repository, however, does not contain the source
code for third-party packages. Instead, it will be downloaded as
needed (Note: you can run
make download to force downloading
packages before building). Package downloads use the Sage mirror
network, the nearest mirror will be determined automatically for
you. This is influenced by the following environment variable:
SAGE_SERVER- Try the specified mirror first, before falling back to the official Sage mirror list. Note that Sage will search the directory
for upstream tarballs.
Here are some of the more commonly used variables affecting the build process:
MAKE- one useful setting for this variable when building Sage is
MAKE='make -jNUM'to tell the
makeprogram to run
NUMjobs in parallel when building. Note that some Sage packages may not support this variable.
Some people advise using more jobs than there are CPU cores, at least if the system is not heavily loaded and has plenty of RAM; for example, a good setting for
NUMmight be between 1 and 1.5 times the number of cores. In addition, the
-loption sets a load limit:
MAKE='make -j4 -l5.5, for example, tells
maketo try to use four jobs, but to not start more than one job if the system load average is above 5.5. See the manual page for GNU
make: Command-line options and Parallel building.
Some users on single-core macOS machines have reported problems when building Sage with
NUMgreater than one.
SAGE_NUM_THREADS- if set to a number, then when building the documentation, parallel doctesting, or running
sage -b, use this many threads. If this is not set, then determine the number of threads using the value of the
MAKE(see above) or
MAKEFLAGSenvironment variables. If none of these specifies a number of jobs, use one thread (except for parallel testing: there we use a default of the number of CPU cores, with a maximum of 8 and a minimum of 2).
V- if set to
0, silence the build. Instead of showing a detailed compilation log, only one line of output is shown at the beginning and at the end of the installation of each Sage package. To see even less output, use:
$ make -s V=0
(Note that the above uses the syntax of setting a Makefile variable.)
SAGE_CHECK- if set to
yes, then during the build process, or when installing packages manually, run the test suite for each package which has one, and stop with an error if tests are failing. If set to
warn, then only a warning is printed in this case. See also
SAGE_CHECKis set to
yes, then the default behavior is to run test suites for all spkgs which contain them. If
SAGE_CHECK_PACKAGESis set, it should be a comma-separated list of strings of the form
!package-name. An entry
package-namemeans to run the test suite for the named package regardless of the setting of
SAGE_CHECK. An entry
!package-namemeans to skip its test suite. So if this is set to
ppl,!python3, then always run the test suite for PPL, but always skip the test suite for Python 3.
As of Sage 9.1, the test suites for the Python 2 and 3 spkgs fail on most platforms. So when this variable is empty or unset, Sage uses a default of
SAGE_INSTALL_GCC- Obsolete, do not use, to be removed
SAGE_INSTALL_CCACHE- by default Sage doesn’t install ccache, however by setting
SAGE_INSTALL_CCACHE=yesSage will install ccache. Because the Sage distribution is quite large, the maximum cache is set to 4G. This can be changed by running
sage -sh -c "ccache --max-size=SIZE", where
SIZEis specified in gigabytes, megabytes, or kilobytes by appending a “G”, “M”, or “K”.
Sage does not include the sources for ccache since it is an optional package. Because of this, it is necessary to have an Internet connection while building ccache for Sage, so that Sage can pull down the necessary sources.
SAGE_DEBUG- controls debugging support. There are three different possible values:
Not set (or set to anything else than “yes” or “no”): build binaries with debugging symbols, but no special debug builds. This is the default. There is no performance impact, only additional disk space is used.
nomeans no debugging symbols (that is, no
gcc -g), which saves some disk space.
SAGE_DEBUG=yes: build debug versions if possible (in particular, Python is built with additional debugging turned on and Singular is built with a different memory manager). These will be notably slower but, for example, make it much easier to pinpoint memory allocation problems.
Instead of using
SAGE_DEBUGone can configure with
SAGE_PROFILE- controls profiling support. If this is set to
yes, profiling support is enabled where possible. Note that Python-level profiling is always available; This option enables profiling in Cython modules.
SAGE_SPKG_INSTALL_DOCS- if set to
yes, then install package-specific documentation to
$SAGE_ROOT/local/share/doc/PACKAGE_NAME/when an spkg is installed. This option may not be supported by all spkgs. Some spkgs might also assume that certain programs are available on the system (for example,
SAGE_DOCBUILD_OPTS- the value of this variable is passed as an argument to
sage --docbuild all htmlor
sage --docbuild all pdfwhen you run
make doc, or
make doc-pdf. For example, you can add
--no-plotto this variable to avoid building the graphics coming from the
.. PLOTdirective within the documentation, or you can add
--include-tests-blocksto include all “TESTS” blocks in the reference manual. Run
sage --docbuild helpto see the full list of options.
SAGE_BUILD_DIR- the default behavior is to build each spkg in a subdirectory of
$SAGE_ROOT/local/var/tmp/sage/build/; for example, build version 7.27.0 of
ipythonin the directory
$SAGE_ROOT/local/var/tmp/sage/build/ipython-7.27.0/. If this variable is set, then build in
$SAGE_BUILD_DIR/ipython-7.27.0/instead. If the directory
$SAGE_BUILD_DIRdoes not exist, it is created. As of this writing (Sage 4.8), when building the standard Sage packages, 1.5 gigabytes of free space are required in this directory (or more if
SAGE_KEEP_BUILT_SPKGS=yes– see below); the exact amount of required space varies from platform to platform. For example, the block size of the file system will affect the amount of space used, since some spkgs contain many small files.
SAGE_BUILD_DIRmust be set to the full path name of either an existing directory for which the user has write permissions, or to the full path name of a nonexistent directory which the user has permission to create. The path name must contain no spaces.
SAGE_KEEP_BUILT_SPKGS- the default behavior is to delete each build directory – the appropriate subdirectory of
$SAGE_BUILD_DIR– after each spkg is successfully built, and to keep it if there were errors installing the spkg. Set this variable to
yesto keep the subdirectory regardless. Furthermore, if you install an spkg for which there is already a corresponding subdirectory, for example left over from a previous build, then the default behavior is to delete that old subdirectory. If this variable is set to
yes, then the old subdirectory is moved to
$SAGE_BUILD_DIR/old), overwriting any already existing file or directory with the same name.
After a full build of Sage (as of version 4.8), these subdirectories can take up to 6 gigabytes of storage, in total, depending on the platform and the block size of the file system. If you always set this variable to
yes, it can take even more space: rebuilding every spkg would use double the amount of space, and any upgrades to spkgs would create still more directories, using still more space.
In an existing Sage installation, running
sage -i -s <package-name>or
sage -f -s <package-name>installs the spkg
<package-name>and keeps the corresponding build directory; thus setting
yesmimics this behavior when building Sage from scratch or when installing individual spkgs. So you can set this variable to
yesinstead of using the
SAGE_FAT_BINARY- to build binaries that will run on the widest range of target CPUs set this variable to
yesbefore building Sage or configure with
--enable-fat-binary. This does not make the binaries relocatable, it only avoids newer CPU instruction set extensions. For relocatable (=can be moved to a different directory) binaries, you must use https://github.com/sagemath/binary-pkg
SAGE_SUDO- set this to
sudo -Eor to any other command prefix that is necessary to write into a installation hierarchy (
SAGE_LOCAL) owned by root or another user. Note that this command needs to preserve environment variable settings (plain
Not all Sage packages currently support
Therefore this environment variable is most useful when a system administrator wishes to install an additional Sage package that supports
SAGE_SUDO, into a root-owned installation hierarchy (
Environment variables dealing with specific Sage packages:
SAGE_MATPLOTLIB_GUI- if set to anything non-empty except
no, then Sage will attempt to build the graphical backend when it builds the matplotlib package.
PARI_CONFIGURE- use this to pass extra parameters to PARI’s
Configurescript, for example to specify graphics support (which is disabled by default). See the file
build/pkgs/pari/spkg-installfor more information.
SAGE_TUNE_PARI: If yes, enable PARI self-tuning. Note that this can be time-consuming. If you set this variable to “yes”, you will also see this:
WARNING: Tuning PARI/GP is unreliable. You may find your build of PARI fails, or PARI/GP does not work properly once built. We recommend to build this package with SAGE_CHECK="yes".
PARI_MAKEFLAGS: The value of this variable is passed as an argument to the
$MAKEcommand when compiling PARI.
Some standard environment variables which are used by Sage:
CC- while some programs allow you to use this to specify your C compiler, not every Sage package recognizes this. If GCC is installed within Sage,
CCis ignored and Sage’s
gccis used instead.
CPP- similarly, this will set the C preprocessor for some Sage packages, and similarly, using it is likely quite risky. If GCC is installed within Sage,
CPPis ignored and Sage’s
cppis used instead.
CXX- similarly, this will set the C++ compiler for some Sage packages, and similarly, using it is likely quite risky. If GCC is installed within Sage,
CXXis ignored and Sage’s
g++is used instead.
FC- similarly, this will set the Fortran compiler. This is supported by all Sage packages which have Fortran code. However, for historical reasons, the value is hardcoded during the initial
makeand subsequent changes to
$FCmight be ignored (in which case, the original value will be used instead). If GCC is installed within Sage,
FCis ignored and Sage’s
gfortranis used instead.
FCFLAGS- the flags for the C compiler, the C++ compiler and the Fortran compiler, respectively. The same comments apply to these: setting them may cause problems, because they are not universally respected among the Sage packages. Note also that
export CFLAGS=""does not have the same effect as
unset CFLAGS. The latter is preferable.
Similar comments apply to other compiler and linker flags like
OPENBLAS_CONFIGURE- adds additional configuration flags for the OpenBLAS package that gets added to the make command. (see trac ticket #23272)
Sage uses the following environment variables when it runs:
DOT_SAGE- this is the directory, to which the user has read and write access, where Sage stores a number of files. The default location is
SAGE_STARTUP_FILE- a file including commands to be executed every time Sage starts. The default value is
BROWSER- on most platforms, Sage will detect the command to run a web browser, but if this doesn’t seem to work on your machine, set this variable to the appropriate command.
Variables dealing with doctesting:
SAGE_TIMEOUT- used for Sage’s doctesting: the number of seconds to allow a doctest before timing it out. If this isn’t set, the default is 300 seconds (5 minutes).
SAGE_TIMEOUT_LONG- used for Sage’s doctesting: the number of seconds to allow a doctest before timing it out, if tests are run using
sage -t --long. If this isn’t set, the default is 1800 seconds (30 minutes).
SAGE_TEST_ITER: these can be used instead of passing the flags
--file-iterations, respectively, to
sage -t. Indeed, these variables are only used if the flags are unset. Run
sage -t -hfor more information on the effects of these flags (and therefore these variables).
Sage sets some other environment variables. The most accurate way to
see what Sage does is to first run
env from a shell prompt to see
what environment variables you have set. Then run
sage --sh -c
env to see the list after Sage sets its variables. (This runs a
separate shell, executes the shell command
env, and then exits
that shell, so after running this, your settings will be restored.)
Alternatively, you can peruse the shell script
Sage also has some environment-like settings. Some of these correspond
to actual environment variables while others have names like
environment variables but are only available while Sage is running. To
see a list, execute
sage.env.[TAB] while running Sage.
This section addresses the question of how a system administrator can install a single copy of Sage in a multi-user computer network.
In the instructions below, we assume that
the directory where you want to install Sage.
First of all, extract the Sage source tarball in
/path/to(this will create the directory
/path/to/sage-x.y). After extracting, you can change the directory name if you do not like
Change the ownership of the
/path/to/sage-x.ydirectory tree to your normal user account (as opposed to
root). This is because Sage will refuse to compile as
$ chown -R user:group /path/to/sage-x.y
Using your normal user account, build Sage. See the Step-by-step installation procedure above.
Make a symbolic link to the
$ ln -s /path/to/sage-x.y/sage /usr/local/bin/sage
Alternatively, copy the Sage script:
$ cp /path/to/sage-x.y/sage /usr/local/bin/sage
If you do this, make sure you edit the line:
at the beginning of the copied
sagescript according to the direction given there to something like:
(note that you have to change
<SAGE_ROOT>above!). It is recommended not to edit the original
sagescript, only the copy at
Optionally, you can test Sage by running:
$ make testlong
make ptestlongwhich tests files in parallel using multiple processes. You can also omit
longto skip tests which take a long time.
This page was last updated in April 2022 (Sage 9.6).