More familiarity with computers may be required to build Sage from
the source code.
If you do have all the pre-requisite tools,
the process should be completely
painless, basically consisting in extracting the source tarball and typing
make. It can take your computer a while to build Sage from the source code,
although the procedure is fully automated and should need no human
Building Sage from the source code has the major advantage that your install will be optimised 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.
Table of contents
See http://wiki.sagemath.org/SupportedPlatforms for the full list of platforms on which Sage is supported and the level of support for these systems.
Sage is supported on a number of Linux, Mac OS X , Sun/Oracle Solaris releases, but not necessarily all versions of these operating systems. There is no native version of Sage which installs on Microsoft Windows, although Sage can be used on Windows with the aid of a virtual machine or the Cygwin Linux API layer.
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 running one of the supported versions of an operating system listed at http://wiki.sagemath.org/SupportedPlatforms. 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 Sage builds its own GCC if needed, a wide variety of C/C++ compilers is supported. Many GCC versions work, from as old as version 3.4.3 to the most recent release. Clang also works. On Solaris systems, the Sun compiler should also work. 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 >= 2.6.
Fortran and compiler suites¶
Sage also needs a Fortran compiler. The only configuration currently supported is matching versions of the C, C++ and Fortran compilers from the GNU Compiler Collection (GCC). Therefore, if you plan on using your own GCC compilers, then make sure that their versions match.
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.
Although some of Sage is written in Python, you do not need Python pre-installed on your computer, since the Sage installation includes virtually everything you need.
After extracting the Sage 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 Mac OS X, there are various developer tools needed which may require some registration on Apple’s developer site; see Mac OS X prerequisite installation.
On Redhat-derived systems not all perl components are installed by default and you might have to install the perl-ExtUtils-MakeMaker package.
On Cygwin, the lapack and liblapack-devel packages are required to provide ATLAS support as the Sage package for ATLAS is not built by default.
To check if you have the above prerequisites installed, for example
command -v 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 prerequisite 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 components.
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
# debian sudo apt-get install binutils gcc make m4 perl tar git # redhat sudo yum install binutils gcc make m4 perl tar git perl-ExtUtils-MakeMaker
to install all general requirements, or, if you don’t want Sage to build its own GCC:
# debian sudo apt-get install binutils gcc g++ gfortran make m4 perl tar git # redhat sudo yum install binutils gcc gcc-c++ gcc-gfortran make m4 perl tar git perl-ExtUtils-MakeMaker
Mac OS X prerequisite installation¶
On OS X systems, you need a recent version of Command Line Tools. It provides all the above requirements.
If you have already installed Xcode (which at the time of writing is freely available in the Mac App Store, or through http://developer.apple.com/downloads/ provided you registered for an Apple Developer account), you can install the command line tools from there as well.
- With OS X Mavericks or Yosemite, run the command
xcode-select --installfrom a Terminal window and click “Install” in the pop-up dialog box.
- Using OS X Mountain Lion or earlier, run Xcode, open its “Downloads” preference pane and install the command line tools from there.
- On pre-Lion OS X systems, the command line tools are not available as a separate download and you have to install the full-blown Xcode supporting your system version.
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 http://developer.apple.com/register/.
- Having done so, you should be able to download it for free at http://developer.apple.com/downloads/index.action?=command%20line%20tools
- Alternately, https://developer.apple.com/opensource/ should have a link to Command Line Tools.
On Solaris, you would use
pkgadd and on OpenSolaris
ipf to install
the necessary software.
On Cygwin, you would use the
As on Linux systems,
ranlib are provided by the
As far as compilers are concerned, you should either install matching versions
gcc4-gfortran packages, or
gcc4-core package alone if you plan on using Sage’s own GCC.
On other systems, check the documentation for your particular operating system.
Specific notes for
On OS X, the system-wide BSD
tar supplied will build Sage, so there is no
need to install the GNU
On Solaris or OpenSolaris, the Sun/Oracle versions of
unsuitable for building Sage.
Therefore, you must have the GNU versions of
tar installed and
they must be the first
tar in your
On Solaris 10, a version of GNU
make may be found at
but you will need to copy it somewhere else and rename it to
The same is true for GNU
tar; a version of GNU
tar may be found at
but it will need to be copied somewhere else and renamed to
It is recommended to create a directory
$HOME/bins-for-sage and to put
the GNU versions of
make in that directory.
Then ensure that
$HOME/bins-for-sage is first in your
That’s because Sage also needs
/usr/ccs/bin in your
execute programs like
/usr/ccs/bin has the
Sun/Oracle versions of
tar in it.
If you attempt to build Sage on AIX or HP-UX, you will need to install both
make and GNU
Using alternative compilers¶
Sage developers tend to use fairly recent versions of GCC. Nonetheless, the Sage build process should succeed with any reasonable C/C++ compiler. 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 set the environment variable
Make sure you have C, C++, and Fortran compilers installed!
Building all of Sage with Clang is currently not supported, see trac ticket #12426.
The following programs are recommended. They are not strictly required at build time or at run time, but provide additional capablities:
- 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 you can install locally inside Sage with the commands:
sage -sh -c '$SAGE_ROOT/src/ext/texlive/texlive-install'
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 texlive install you will
probably need a number of optional texlive packages, for example
country-specific babel packages for the localized Sage
documentation. The required texlive packages are listed in
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.
Notebook additional features¶
By default, the Sage notebook uses the
protocol when you type the command
To run the notebook in secure mode by typing
uses the HTTPS protocol,
or to use OpenID authentication,
you need to follow specific installation steps described in
Building the notebook with SSL support.
Although all necessary components are provided through Sage optional packages,
i.e. you can install a local version of OpenSSL
by using Sage’s openssl package and running
sage -i openssl as suggested
in Building the notebook with SSL support (this requires an Internet connection),
you might prefer to install OpenSSL and the OpenSSL development headers
globally on your system.
On Linux systems, those are usually provided by the libssl and libssl-dev packages and can be installed using:
sudo apt-get install libssl libssl-dev
or similar commands.
On Linux systems, the OpenSSH server, client and utilities are usually provided by the openssh-server and openssh-client packages and can be installed using:
sudo apt-get install openssh-server openssh-client
or similar commands.
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 python2 # rebuild Python 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.
Installation from source is (potentially) very easy, because the distribution contains (essentially) everything on which Sage depends.
Make sure there are no spaces in the path name for the directory in which you build: several of Sage’s components will not build if there are spaces in the path. Running Sage from a directory with spaces in its name will also fail.
Go to http://www.sagemath.org/download-source.html, select a mirror, and download the file
This tarfile contains the source code for Sage and the source for all programs on which Sage depends. Note that this file is not compressed; it’s just a plain tarball (which happens to be full of compressed files).
Download it into any directory you have write access to, preferably on a fast filesystem, avoiding NFS and the like. On personal computers, any subdirectory of your
HOMEdirectory should do. The directory where you built Sage is NOT hardcoded. You should be able to safely move or rename that directory. (It’s a bug if this is not the case.)
Extract the tarfile:
tar xvf sage-x.y.tar
This creates a directory
Change into that directory:
This is Sage’s home directory. It is also referred to as
SAGE_ROOTor the top level Sage directory.
Optional, but highly recommended: Read the
On OSX 10.4, OS 10.5, Solaris 10 and OpenSolaris, if you wish to build a 64-bit version of Sage, assuming your computer and operating system are 64-bit, type:
It should be noted that as of April 2011, 64-bit builds of Sage on both Solaris 10 and OpenSolaris are not very stable, so you are advised not to set
yes. This will then create stable 32-bit versions of Sage. See http://wiki.sagemath.org/solaris for the latest information.
Start the build process:
or if your system supports multiprocessing and you want to use several processes to build Sage:
MAKE='make -jNUM' make
to tell the
makeprogram to run
NUMjobs in parallel when building Sage. This compiles Sage and all its dependencies.
Mac OS X allows changing directories without using exact capitalization. Beware of this convenience when compiling for OS X. Ignoring exact capitalization when changing into
SAGE_ROOTcan lead to build errors for dependencies requiring exact capitalization in path names.
Note that 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. There has been a bug reported (see trac ticket #9551) in Sage which would have overwritten a system file had the user been 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 http://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, OS X, 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.)
See Make targets for some targets for the
makecommand, Environment variables for additional informatio on useful environment variables used by Sage, and Building the notebook with SSL support for additional instruction on how to build the notebook with SSL support.
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 ---------------------------------------------------------------------- | Sage Version 5.8, Release Date: 2013-03-15 | | Type "notebook()" for the browser-based notebook interface. | | 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 http://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
#!/bin/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 OS X 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 http://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!
Building the notebook with SSL support¶
Read this section if you are intending to run a Sage notebook server for multiple users.
For security, you may wish users to access the server using the HTTPS protocol
(i.e., to run
You also may want to use OpenID for user authentication.
The first of these requires you to install
and they both require OpenSSL.
If you have OpenSSL and the OpenSSL development headers installed on your system, you can install pyOpenSSL by building Sage and then typing:
./sage -i pyopenssl
make ssl builds Sage and installs pyOpenSSL at once.
Note that these commands require Internet access.
If you are missing either OpenSSL or OpenSSL’s development headers, you can install a local copy of both into your Sage installation first. Ideally, this should be done before installing Sage; otherwise, you should at least rebuild Sage’s Python, and ideally any part of Sage relying on it. The procedure is as follows (again, with a computer connected to the Internet). Starting from a fresh Sage tarball:
./sage -i openssl make ssl
And if you’ve already built Sage:
./sage -i openssl ./sage -f python2 make ssl
The third line will rebuild all parts of Sage that depend on Python; this can take a while.
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-clean, 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-cleanremoves 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 clean upstream tarballs, and it searches the directories
for old-style Sage packages.
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 not all Sage packages (e.g. ATLAS) 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 OS X 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).
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. 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
mpir,!python, then always run the test suite for MPIR, but always skip the test suite for Python.
As of this writing (April 2013, Sage 5.8), the test suite for the Python spkg fails on most platforms. So when this variable is empty or unset, Sage uses a default of
SAGE64- if set to
yes, then build a 64-bit binary on platforms which default to 32-bit, even though they can build 64-bit binaries. It adds the compiler flag
-m64when compiling programs. The
SAGE64variable is mainly of use on OS X (pre 10.6), Solaris and OpenSolaris, though it will add the
-m64flag on any operating system. If you are running Linux or version 10.6 or later of OS X on a 64-bit machine, then Sage will automatically build a 64-bit binary, so this variable does not need to be set.
CFLAG64- default value
-m64. If Sage detects that it should build a 64-bit binary, then it uses this flag when compiling C code. Modify it if necessary for your system and C compiler. This should not be necessary on most systems – this flag will typically be set automatically, based on the setting of
SAGE64, for example.
SAGE_INSTALL_GCC- by default, Sage will automatically detect whether to install the GNU Compiler Collection (GCC) package or not (depending on whether C, C++, and Fortran compilers are present and the versions of those compilers). Setting
SAGE_INSTALL_GCC=yeswill force Sage to install GCC. Setting
SAGE_INSTALL_GCC=nowill prevent Sage from installing GCC.
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.
SAGE_PROFILE- controls profiling support. If this is set to
yes, profiling support is enabled where possible. Note that Python-level profiling is always avaliable; 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_DOC_MATHJAX- by default, any LaTeX code in Sage’s documentation is processed by MathJax. If this variable is set to
no, then MathJax is not used – instead, math is processed using LaTeX and converted by dvipng to image files, and then those files are included into the documentation. Typically, building the documentation using LaTeX and dvipng takes longer and uses more memory and disk space than using MathJax.
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
--no-teststo omit 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 3.8.3.p12 of
atlasin the directory
$SAGE_ROOT/local/var/tmp/sage/build/atlas-3.8.3.p12/. If this variable is set, then build in
$SAGE_BUILD_DIR/atlas-3.8.3.p12/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. 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 (
Variables to set if you’re trying to build Sage with an unusual setup, e.g., an unsupported machine or an unusual compiler:
SAGE_PORT- if you try to build Sage on a platform which is recognized as being unsupported (e.g. AIX, or HP-UX), or with a compiler which is unsupported (anything except GCC), you will see a message saying something like:
You are attempting to build Sage on IBM's AIX operating system, which is not a supported platform for Sage yet. Things may or may not work. If you would like to help port Sage to AIX, please join the sage-devel discussion list -- see http://groups.google.com/group/sage-devel The Sage community would also appreciate any patches you submit. To get past this message and try building Sage anyway, export the variable SAGE_PORT to something non-empty.
If this is case and you want to try to build Sage anyway, follow the directions: set
SAGE_PORTto something non-empty (and expect to run into problems).
Environment variables dealing with specific Sage packages:
SAGE_MP_LIBRARY- to use an alternative library in place of
MPIRfor multiprecision integer arithmetic. Supported values are
SAGE_ATLAS_ARCH- if you are compiling ATLAS (in particular, if
SAGE_ATLAS_LIBis not set), you can use this environment variable to set a particular architecture and instruction set extension, to control the maximum number of threads ATLAS can use, and to trigger the installation of a static library (which is disabled by default unless building our custom shared libraries fails). The syntax is
While ATLAS comes with precomputed timings for a variety of CPUs, it only uses them if it finds an exact match. Otherwise, ATLAS runs through a lengthy automated tuning process in order to optimize performance for your particular system, which can take several days on slow and unusual systems. You drastically reduce the total Sage compile time if you manually select a suitable architecture. It is recommended to specify a suitable architecture on laptops or other systems with CPU throttling or if you want to distribute the binaries. Available architectures are
and instruction set extensions are
In addition, you can also set
SAGE_ATLAS_ARCH=fastwhich picks defaults for a modern (2-3 year old) CPU of your processor line, and
SAGE_ATLAS_ARCH=basewhich picks defaults that should work for a ~10 year old CPU.
would be appropriate for a Core i7 CPU.
SAGE_ATLAS_LIB- if you have an installation of ATLAS on your system and you want Sage to use it instead of building and installing its own version of ATLAS, set this variable to be the directory containing your ATLAS installation. It should contain the files
libptf77blasfor multi-threaded computations), with extensions
.dylib. For backward compatibility, the libraries may also be in the subdirectory
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
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
SAGE_PATH- a colon-separated list of directories which Sage searches when trying to locate Python libraries.
SAGE_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.
Sage overrides the user’s settings of the following variables:
MPLCONFIGDIR- ordinarily, this variable lets the user set their matplotlib config directory. Due to incompatibilies in the contents of this directory among different versions of matplotlib, Sage overrides the user’s setting, defining it instead to be
VERreplaced by the current matplotlib version number.
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_PICKLE_JAR- if you want to update the standard pickle jar, set this to something non-empty and run the doctest suite. See the documentation for the functions
$SAGE_ROOT/src/sage/structure/sage_object.pyx, online here (picklejar) and here (unpickle_all).
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 ptestlongwhich tests files in parallel using multiple processes. You can also omit
longto skip tests which take a long time.
Usually Sage will build ATLAS with architectural defaults that are not tuned to your particular CPU. In particular, if your CPU has powersaving enabled then no accurate timings can be made to tune the ATLAS build for your hardware. If BLAS performance is critical for you, you must recompile ATLAS after installing Sage either with architecture settings that match your hardware, or run through ATLAS’ automatic tuning process where timings of different implementations are compared and the best choice used to build a custom ATLAS library. To do so, you have to
- Leave the computer idle while you are reinstalling ATLAS. Most of ATLAS will intentionally only compile/run on a single core. Accurate timings of cache edges require that the CPU is otherwise idle.
- Make sure that CPU powersaving mode (that is, anything but the
performanceCPU scaling governor in Linux) is turned off when building ATLAS. This requires administrator privileges.
- If your architecture is listed in
SAGE_ATLAS_ARCH, you should set it as it can help ATLAS in narrowing down the timing search.
To help you disable CPU power saving, Sage includes an
that will turn off CPU powersave and rebuild ATLAS.
The script will call
sudo to gain the necessary rights, which may prompt
you for your password. For example:
will run through the full automated tuning, and:
would be appropriate if you have a Core i3/5/7 processor with AVX support.
This page was last updated in July 2016 (Sage 7.3).