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 awaywith less (be sure to have some swap space in this case).

Software prerequisites and recommended packages¶

Sage depends ona large number of software packages. Sage provides its own softwaredistribution providing most of these packages, so you do not have toworry about having to download and install these packages yourself.

If you extracted Sage from a source tarball, the subdirectoryupstream contains the source distributions for all standardpackages on which Sage depends. If cloned from a git repository, theupstream tarballs will be downloaded, verified, and cached as part ofthe Sage installation process.

However, there are minimal prerequisites for building Sage thatalready must be installed on your system:

• Fundamental system packages required for installing from source

• C/C++ compilers

If you have sufficient privileges (for example, on Linux you canusesudo to become theroot user), then you can install these packagesusing the commands for your platform indicated in the pages linked above.If you do not have the privileges to do this, ask your system administrator todo this for you.

In addition to these minimal prerequisites, we strongly recommend to use systeminstallations of the following:

• Fortran compiler

• Python

Sage developers will also need thesystem packages required forbootstrapping; they cannot beinstalled by Sage.

When the./configure script runs, it will check for the presence of manypackages (including the above) and inform you of any that aremissing or have unsuitable versions.Please read the messages that./configure prints: It will inform you which additional system packagesyou can install to avoid having to build them from source. This can save a lot oftime.

The following sections provide the commands to install a largerecommended set of packages on various systems, which will minimizethe time it takes to build Sage. This is intended as a convenientshortcut, but of course you can choose to take a more fine-grainedapproach.

Linux system package installation¶

We recommend that you install the following packages, depending on your distribution:

  $sudoapt-getinstallbcbinutilsbzip2ca-certificatescliquercmakecurl\ecleclib-toolsfflas-ffpackflexg++gapgccgengetoptgfangfortran\glpk-utilsgmp-ecmlcalclibatomic-ops-devlibboost-dev\libbraiding-devlibbrial-devlibbrial-groebner-devlibbz2-dev\libcdd-devlibcdd-toolslibcliquer-devlibcurl4-openssl-devlibec-dev\libecm-devlibffi-devlibflint-devlibfplll-devlibfreetype-dev\libgap-devlibgc-devlibgd-devlibgf2x-devlibgivaro-devlibglpk-dev\libgmp-devlibgsl-devlibhomfly-devlibiml-devliblfunction-dev\liblinbox-devliblrcalc-devliblzma-devlibm4ri-devlibm4rie-dev\libmpc-devlibmpfi-devlibmpfr-devlibncurses5-devlibntl-dev\libopenblas-devlibpari-devlibplanarity-devlibppl-dev\libprimecount-devlibprimesieve-devlibpython3-devlibqhull-dev\libreadline-devlibrw-devlibsingular4-devlibsqlite3-devlibssl-dev\libsuitesparse-devlibsymmetrica2-devlibz-devlibzmq3-devm4make\maximamaxima-sagemesonnautyninja-buildopensslpalppari-doc\pari-elldatapari-galdatapari-galpolpari-gp2cpari-seadatapatch\patchelfperlpkg-configplanarityppl-devpython3python3-setuptools\python3-venvqhull-binsingularsingular-docsqlite3sympowtachyon\tartexinfotoxxz-utils

  $sudoyuminstall--setopt=tsflags=L-functionL-function-develSingular\Singular-develbinutilsboost-develbrialbrial-develbzip2\bzip2-develcddlibcddlib-develcliquercliquer-develcmakecurl\diffutilsecleclibeclib-develfflas-ffpack-develfindutilsflex\flintflint-develgapgap-coregap-develgap-libsgap-pkg-ace\gap-pkg-aclibgap-pkg-alnuthgap-pkg-anupqgap-pkg-atlasrep\gap-pkg-autodocgap-pkg-automatagap-pkg-autpgrpgap-pkg-browse\gap-pkg-caratinterfacegap-pkg-circlegap-pkg-congruencegap-pkg-crisp\gap-pkg-cryptinggap-pkg-crystcatgap-pkg-curlinterfacegap-pkg-cvec\gap-pkg-datastructuresgap-pkg-digraphsgap-pkg-edimgap-pkg-ferret\gap-pkg-fgagap-pkg-fininggap-pkg-floatgap-pkg-formatgap-pkg-forms\gap-pkg-fplsagap-pkg-frgap-pkg-francygap-pkg-genss\gap-pkg-groupoidsgap-pkg-grpconstgap-pkg-imagesgap-pkg-io\gap-pkg-irredsolgap-pkg-jsongap-pkg-jupytervizgap-pkg-lpres\gap-pkg-nqgap-pkg-openmathgap-pkg-orbgap-pkg-permutgap-pkg-polenta\gap-pkg-polycyclicgap-pkg-primgrpgap-pkg-profilinggap-pkg-radiroot\gap-pkg-recoggap-pkg-resclassesgap-pkg-scscpgap-pkg-semigroups\gap-pkg-singulargap-pkg-smallgrpgap-pkg-smallsemigap-pkg-sophus\gap-pkg-spinsymgap-pkg-standardffgap-pkg-tomlibgap-pkg-transgrp\gap-pkg-transgrp-datagap-pkg-utilsgap-pkg-uuidgap-pkg-xmod\gap-pkg-zeromqinterfacegcgc-develgccgcc-c++gcc-gfortrangd\gd-develgengetoptgf2xgf2x-develgfangivarogivaro-develglpk\glpk-develglpk-utilsgmpgmp-develgmp-ecmgmp-ecm-develgsl\gsl-develimliml-develinfolibatomic_opslibatomic_ops-devel\libbraiding-devellibcurl-devellibffilibffi-devellibfplll\libfplll-devellibgaplibhomfly-devellibmpclibmpc-devellinbox\linbox-devellrcalc-develm4m4ri-develm4rie-develmakemathjax3\maximamaxima-runtime-eclmesonmpfr-develnautyncurses-devel\ninja-buildntl-developenblas-developensslopenssl-develpalp\pari-develpari-elldatapari-galdatapari-galpolpari-gppari-seadata\patchpatchelfperlperl-ExtUtils-MakeMakerperl-IPC-Cmdpkg-config\planarityplanarity-develpplppl-develprimecountprimecount-devel\primesieveprimesieve-develpython3python3-develpython3-setuptools\python3-virtualenvqhullqhull-develreadline-develrw-develsqlite\sqlite-develsuitesparsesuitesparse-develsymmetrica-develsympow\tachyontachyon-develtartexinfotoxwhichxgapxzxz-develzeromq\zeromq-develzlib-devel

  $sudopacman-Sbcbinutilsboostbrialcblascddlibcliquercmakeecl\eclibfflas-ffpackfplllgapgcgccgcc-fortrangdgf2xgfanglpkgsl\imllapacklcalclibatomic_opslibbraidinglibhomflylinboxlrcalcm4\m4rim4riemakemaxima-fasmesonnautyninjaopenblasopensslpalp\paripari-elldatapari-galdatapari-galpolpari-seadatapatchperl\pkgconfplanaritypplprimecountprimesievepythonpython-toxqhull\rankwidthreadlinesingularsqlite3suitesparsesymmetricasympow\tachyontarwhichzeromq

  $sudozypperinstallbcbinutilsboost-develbrial-develbzip2\ca-certificatescddlib-toolscliquercliquer-develcmakecurl\diffutilsedge-addition-planarity-suite\edge-addition-planarity-suite-develfindutilsflint-develfplll\fplll-develgawkgccgcc-c++gcc-fortrangdgfanglibc-locale-base\glpkglpk-develgmp-develgzipiml-devellibbraiding-devel\libhomfly-devellibopenssl-3-devellibprimecount-develm4makemathjax\maxima-exec-clispmesonmpc-develmpfi-develnautynauty-develninja\ntl-developenblas-develpari-develpari-galdatapari-gppatch\patchelfperlpkgconfpkgconfig\(atomic_ops\)pkgconfig\(bdw-gc\)\pkgconfig\(bzip2\)pkgconfig\(cddlib\)pkgconfig\(fflas-ffpack\)\pkgconfig\(fplll\)pkgconfig\(freetype2\)pkgconfig\(gdlib\)\pkgconfig\(gf2x\)pkgconfig\(givaro\)pkgconfig\(gsl\)\pkgconfig\(libcurl\)pkgconfig\(libffi\)pkgconfig\(liblzma\)\pkgconfig\(libpng16\)pkgconfig\(libzmq\)pkgconfig\(linbox\)\pkgconfig\(m4ri\)pkgconfig\(m4rie\)pkgconfig\(mpfr\)\pkgconfig\(ncurses\)pkgconfig\(ncursesw\)pkgconfig\(readline\)\pkgconfig\(sqlite3\)pkgconfig\(zlib\)ppl-develprimecountprimesieve\python3python3-develpython3-setuptoolsqhull-develreadline-devel\suitesparse-develsympowtachyontartexinfowhichxz

  $sudoxbps-installSuiteSparse-develbashbcbinutilsboost-devel\brial-develbzip2-develcddlib-develcliquer-develcmakecurl\diffutilsecleclib-develecm-develfflas-ffpackflintlib-devel\fplll-develfreetype-develgc-develgccgcc-fortrangd-develgengetopt\gf2x-develgfangivaro-develglpk-develgmp-develgmpxx-devel\gsl-develgzipiml-devellcalc-devellibatomic_ops-devel\libbraiding-devellibcurl-devellibffi-devellibgomp-devel\libhomfly-develliblzma-devellibmpc-devellibpng-devellibqhull-devel\libxcrypt-devellinbox-devellrcalc-develm4m4ri-develm4rie-devel\makemathjaxmaxima-eclmpfi-develmpfr-develnautyncurses-devel\ninjantl-developenblas-developenssl-develpalpparipari-devel\pari-elldata-smallpari-galdatapari-galpol-smallpari-seadatapatch\patchelfperlpkgconfplanarity-develppl-develprimecount-devel\primesieve-develpython3python3-appdirspython3-develpython3-distlib\python3-filelockpython3-setuptoolspython3-virtualenvqhull\rankwidth-develreadline-develsingularsqlite-develsymmetrica-devel\sympowtachyontartexinfotoxwhichxzzeromq-develzlib-devel

If you wish to do Sage development, we recommend that you additionallyinstall the following:

  $sudoapt-getinstallautoconfautomakeghgitgpgconflibtool\openssh-clientpkg-config

  $sudoyuminstallautoconfautomakeghgitgnupg2libtoolopenssh\pkg-config

  $sudopacman-Sautoconfautomakegitgithub-clignupglibtoolopenssh\pkgconf

  $sudozypperinstallautoconfautomakeghgitgpg2libtoolopenssh\pkgconfig

  $sudoxbps-installautoconfautomakegitgithub-clignupg2libtool\mk-configureopensshpkg-configxtools

For all users, we recommend that you install the following systempackages, which provide additional functionality and cannot beinstalled by Sage. In particular, this includesLaTeX and related tools. In addition to a base install ofTeXLive, our lists of system packages below includeeverything that is needed for generating the Sage documentation in PDFformat. For converting Jupyter notebooks to PDF, also the documentconverterpandoc is needed. For makinganimations, Sage needs to use one of the packagesFFmpeg andImageMagick.

  $sudoapt-getinstalldefault-jdkdvipngffmpegfonts-freefont-otf\imagemagicklatexmklibavdevice-devlibjpeg-devpandoctex-gyre\texlive-fonts-recommendedtexlive-lang-cyrillictexlive-lang-english\texlive-lang-europeantexlive-lang-frenchtexlive-lang-german\texlive-lang-italiantexlive-lang-japanesetexlive-lang-polish\texlive-lang-portuguesetexlive-lang-spanishtexlive-latex-extra\texlive-luatextexlive-xetexxindy

  $sudoyuminstallImageMagickffmpeg-freeffmpeg-free-devel\gnu-free-mono-fontsgnu-free-sans-fontsgnu-free-serif-fontslatexmk\libjpeg-turbo-develpandoctexlivetexlive-collection-langcyrillic\texlive-collection-langeuropeantexlive-collection-langfrench\texlive-collection-langgermantexlive-collection-langitalian\texlive-collection-langjapanesetexlive-collection-langpolish\texlive-collection-langportuguesetexlive-collection-langspanish\texlive-collection-latexextratexlive-gnu-freefonttexlive-luatex\texlive-xindy

  $sudopacman-Sffmpeggnu-free-fontsimagemagicklibjpeg-turbopandoc\texlive-coretexlive-langcyrillictexlive-langjapanese\texlive-latexextratexlive-luatex

  $sudozypperinstallImageMagickffmpeggnu-free-fontslibjpeg-develpandoc\texlivetexlive-luatexxindy

  $sudoxbps-installImageMagickffmpegfreefont-ttflibjpeg-turbo-devel\pandoctexlive

In addition to these, if you don’t want Sage to build optional packages that mightbe available from your OS, cf. the growing list of such packages onIssue #27330,install:

  $sudoapt-getinstall4ti2clangcoinor-cbccoinor-libcbc-devfricas\graphvizlibfile-slurp-perllibgiac-devlibgraphviz-devlibigraph-dev\libisl-devlibjson-perllibmongodb-perllibnauty-devlibperl-dev\libpolymake-devlibsvg-perllibtbb-devlibterm-readkey-perl\libterm-readline-gnu-perllibxml-libxslt-perllibxml-writer-perl\libxml2-devlrslibpari-gp2cpdf2svgpolymakesbclxcas

  $sudoyuminstall4ti24ti2-develblissbliss-develclangcoin-or-Cbc\coin-or-Cbc-develcoxetercoxeter-develcoxeter-toolsgiacgiac-devel\gp2cgraphvizgraphviz-develigraphigraph-develislisl-devel\libnautylibnauty-devellibsemigroupslibsemigroups-devel\libxml2-devellrsliblrslib-develpari-galpolpari-seadatapdf2svg\perl-ExtUtils-Embedperl-File-Slurpperl-JSONperl-MongoDBperl-SVG\perl-Term-ReadLine-Gnuperl-TermReadKeyperl-XML-LibXML\perl-XML-LibXSLTperl-XML-Writerpolymakesbcltbbtbb-devel

  $sudopacman-S4ti2blissclangcoin-or-cbccoxetergiacgraphvizigraph\intel-oneapi-tbblibxml2lrspari-elldatapari-galpolpari-seadata\pdf2svgperl-term-readline-gnupolymakesbclsymengine

  $sudozypperinstall4ti24ti2-develblissbliss-develcoxeterfricas\giac-develgp2cgraphvizlibxml2llvmlrsliblrslib-develpari-elldata\pari-galpolpari-nftablespari-seadatapdf2svg\perl\(Term::ReadLine::Gnu\)pkgconfig\(isl\)\pkgconfig\(libsemigroups\)polymakesbclsymenginetbb

  $sudoxbps-installCoinMP-develclanggiac-develgp2cgraphviz\graphviz-develigraph-develisl-devellibxml2-develnauty-devel\pari-elldata-smallpari-galpol-smallpari-nftablespari-seadata\perl-File-Slurpperl-JSONperl-SVGperl-Term-ReadKey\perl-Term-ReadLine-Gnuperl-XML-LibXMLperl-XML-LibXSLT\perl-XML-Writersbcltbb-devel

macOS prerequisites¶

On macOS systems, you need a recent version ofCommand Line Tools.It provides all the above requirements.

Run the commandxcode-select--install from a Terminal window and click “Install”in the pop-up dialog box.

If you have already installedXcode(which at the time of writing is freely available in the Mac App Store,or throughhttps://developer.apple.com/downloads/ provided you registered for anApple Developer account), you can install the command line tools fromthere as well.

If you have not installedXcodeyou can get these tools as a relatively small download, but it does requirea registration.

• First, you will need to register as an Apple Developer athttps://developer.apple.com/register/.

• Having done so, you should be able to download it for free athttps://developer.apple.com/downloads/index.action?=command%20line%20tools

• Alternately,https://developer.apple.com/opensource/ should have a linkto Command Line Tools.

macOS package installation¶

If you use theHomebrew package manager, you can install the following:

  $brewinstallbdw-gcboostbzip2cddlibcmakecurleclflintfplllfreetype\gccgdgengetoptgfortranglpkgmpgpatchgsllibatomic_opslibffi\libiconvlibmpclibpngmaximamesonmpfimpfrnautyncursesninjantl\openblasopensslparipari-elldatapari-galdatapari-galpol\pari-seadatapatchelfpkg-configpplprimecountprimesieve\python-setuptoolspython3qhullreadlinesingularsqlitesuite-sparse\texinfotoxxzzeromqzlib

Some Homebrew packages are installed “keg-only,” meaning that they arenot available in standard paths. To make them accessible when buildingSage, run

$sourceSAGE_ROOT/.homebrew-build-env

(replacingSAGE_ROOT by Sage’s home directory). You can add acommand like this to your shell profile if you want the settings topersist between shell sessions.

If you wish to do Sage development, we recommend that you additionallyinstall the following:

  $brewinstallautoconfautomakeghgitgnupglibtoolpkg-config

For all users, we recommend that you install the following system packages,which provide additional functionality and cannot be installed by Sage:

  $brewinstallffmpegimagemagickjpeg-turbopandoctexinfo

Some additional optional packages are taken care of by:

  $brewinstallapaffenholz/polymake/polymakecbcgraphvizigraphisllibxml2\llvmnautypdf2svgsbclsymenginetbb

WSL prerequisites¶

Other platforms¶

On Solaris, you would usepkgadd and on OpenSolarisipf to installthe 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:

  $condadeactivate

• Repeat the command untilcondainfo shows:

  $condainfoactive environment : None...

Then SageMath will be built either using the compilers provided by theoperating system, or its own compilers.

Tcl/Tk (and system’s Python)¶

If you want to useTcl/Tk libraries in Sage, and youare going to use your OS’s Python3 as Sage’s Python, you merely need to installitsTkinter module. On Linux systems, it is usually provided by thepython3-tk or a similarly named (e.g.python3-tkinter) package,which can be installed using:

$sudoapt-getinstallpython3-tk

or similar commands.

Tcl/Tk (and Sage’s own Python)¶

If you want to useTcl/Tk libraries in Sage,and you are going to build Sage’s Python from source, you need to installthese, and the corresponding headers.On Linux systems, these are usually provided by thetk andtk-dev(ortk-devel) packages which can be installed using:

$sudoapt-getinstalltktk-dev

or similar commands.

Sage’s Python will then automatically recognize your system’s install of Tcl/Tk.If you installed Sage first, all is not lost. You just need to rebuildSage’s Python and any part of Sage relying on it:

$sage-fpython3# rebuild Python3$make# rebuild components of Sage depending on Python

after installing the Tcl/Tk development libraries as above.

If

sage:import_tkintersage:importTkinter

does not raise anImportError, then it worked.

Standard environment controlling the build process¶

Here are some of the more commonly used variables affecting the build process:

MAKEFLAGS¶

This variable can be set to tell themake program to build things inparallel. Set it to-jNUM to runNUM jobs in parallel when building.Add-lNUM to tell make not to spawn more processes when the load exceedsNUM.

A good value for this variable isMAKEFLAGS="-j$(nproc)-l$(nproc).5" onLinux andMAKEFLAGS="-j$(sysctl-nhw.ncpu)-l$(sysctl-nhw.ncpu).5" onmacOS. This instructs make to use all the execution threads of your CPU whilebounding the load if there are other processes generating load. If yoursystem does not have a lot of RAM, you might want to choose lower limits, ifyou have lots of RAM, it can sometimes be beneficial to set these limitsslightly higher.

Note that some parts of the SageMath build system do not respect thisvariable, e.g., when ninja gets invoked, it figures out the number ofprocesses to use on its own so the number of processes and the system loadyou see might exceed the number configured here.

See the manual page for GNUmake:Command-line optionsandParallel building.

V¶

If set to0, silence the build. Instead of showing a detailedcompilation log, only one line of output is shown at the beginningand at the end of the installation of each Sage package. To seeeven less output, use:

$make-sV=0

(Note that the above uses the syntax of setting a Makefile variable.)

CC¶

While some programs allow you to use this to specify your Ccompiler,not every Sage package recognizes this.If GCC is installed within Sage,CC is ignored and Sage’sgccis used instead.

CPP¶

Similarly, this will set the C preprocessor for some Sagepackages, and similarly, using it is likely quite risky.If GCC is installed within Sage,CPP is ignored and Sage’scppis used instead.

CXX¶

Similarly, this will set the C++ compiler for some Sagepackages, and similarly, using it is likely quite risky.If GCC is installed within Sage,CXX is ignored and Sage’sg++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 initialmake and subsequent changes to$FC might be ignored (in which case,the original value will be used instead).If GCC is installed within Sage,FC is ignored and Sage’sgfortran is used instead.

CFLAGS¶

CXXFLAGS¶

FCFLAGS¶

The flags forthe C compiler, the C++ compiler and the Fortran compiler, respectively.The same comments apply to these: setting them may cause problems, becausethey are not universally respected among the Sage packages. Notealso thatexportCFLAGS="" does not have the same effect asunsetCFLAGS. The latter is preferable.

CPPFLAGS¶

LDFLAGS¶

CXXFLAG64¶

LDFLAG64¶

LD¶

Similar comments apply to these compiler and linker flags.

Sage-specific environment variables controlling the build process¶

SAGE_SERVER¶

The Sage source tarball already includes the sources for all standardpackages, that is, it allows you to build Sage without internetconnection. The git repository, however, does not contain the sourcecode for third-party packages. Instead, it will be downloaded asneeded (note: you can runmakedownload to force downloadingpackages before building).

IfSAGE_SERVER is set, the specified Sage mirror is contactedfirst. Note that Sage will search the directorySAGE_SERVER/spkg/upstream for upstream tarballs.

If downloading a file from there fails orSAGE_SERVER is not set,files will be attempted to download from release assets of theSage GitHub repository.

If that fails too, the Sage mirror network is contacted to determinethe nearest mirrors.

This sequence of operations is defined by the files in the directorySAGE_ROOT/.upstream.d.

SAGE_NUM_THREADS¶

If set to a number, then when rebuilding withsage-b orparallel doctesting withsage-t-p0, use at most this manythreads.

If this is not set, then determine the number of threads using the value oftheMAKE (see above) orMAKEFLAGS environment variables.If none of these specifies a number of jobs,

• sage-b only uses one thread

• sage-t-p0 uses a default of the number of CPU cores, with amaximum of 8 and a minimum of 2.

Whensage-t-p runs under the control of the GNUmakejobserver, then Sage will request as most this number of job slots.

SAGE_CHECK¶

If set toyes, then during the build process,or when installing packages manually,run the test suite for each package which has one, and stop with an errorif tests are failing. If set towarn, then only a warning is printedin this case.See alsoSAGE_CHECK_PACKAGES.

SAGE_CHECK_PACKAGES¶

IfSAGE_CHECK is set toyes,then the default behavior is to run test suites for all spkgs which containthem.IfSAGE_CHECK_PACKAGES is set, it should be a comma-separated listof strings of the formpackage-name or!package-name.An entrypackage-name means to run the test suite for the named packageregardless of the setting ofSAGE_CHECK.An entry!package-name means to skip its test suite.So if this is set toppl,!python3, then always run the test suite forPPL, but always skip the test suite for Python 3.

Note

As of Sage 9.1, the test suites for the Python 2 and 3 spkgs failon most platforms. So when this variable is empty or unset, Sageuses a default of!python2,!python3.

SAGE_INSTALL_GCC¶

Obsolete, do not use, to be removed

SAGE_INSTALL_CCACHE¶

By default Sage doesn’t installccache,however by settingSAGE_INSTALL_CCACHE=yes Sage will install ccache.Because the Sage distribution is quite large, the maximum cache is set to 4G.This can be changed by runningsage-sh-c"ccache--max-size=SIZE",whereSIZE is specified in gigabytes, megabytes, or kilobytes byappending 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 whilebuilding ccache for Sage, so that Sage can pull down the necessarysources.

SAGE_DEBUG¶

Controls debugging support. There are three different possible values:

• Not set (or set to anything else than “yes” or “no”): build binaries withdebugging symbols, but no special debug builds.This is the default.There is no performance impact, only additional disk space is used.

• SAGE_DEBUG=no:no means no debugging symbols (that is, nogcc-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 builtwith a different memory manager).These will be notably slower but, for example, make it much easier topinpoint memory allocation problems.

Instead of usingSAGE_DEBUG one can configure with--enable-debug={no|symbols|yes}.

SAGE_PROFILE¶

Controls profiling support. If this is settoyes, profiling support is enabled where possible. Note thatPython-level profiling is always available; this option enablesprofiling in Cython modules.

SAGE_BUILD_DIR¶

The default behavior is to build each spkg in asubdirectory of$SAGE_ROOT/local/var/tmp/sage/build/; forexample, build version 7.27.0 ofipython in 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_DIR does 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 ifSAGE_KEEP_BUILT_SPKGS=yes – see below); the exact amount of requiredspace varies from platform to platform.For example, the block size of the file system will affect the amount ofspace used, since some spkgs contain many small files.

Warning

The variableSAGE_BUILD_DIR must be set to the full path nameof either an existing directory for which the user has write permissions,or to the full path name of a nonexistent directory which the user haspermission to create.The path name must containno spaces.

SAGE_KEEP_BUILT_SPKGS¶

The default behavior is to delete eachbuild directory – the appropriate subdirectory of$SAGE_ROOT/local/var/tmp/sage/build or$SAGE_BUILD_DIR – after each spkgis successfully built, and to keep it if there were errors installing thespkg.Set this variable toyes to keep the subdirectory regardless.Furthermore, if you install an spkg for which there is already acorresponding subdirectory, for example left over from a previous build,then the default behavior is to delete that old subdirectory.If this variable is set toyes, then the old subdirectory is moved to$SAGE_ROOT/local/var/tmp/sage/build/old/ (or$SAGE_BUILD_DIR/old),overwriting any already existing file or directory with the same name.

Note

After a full build of Sage (as of version 4.8), these subdirectories cantake up to 6 gigabytes of storage, in total, depending on the platformand the block size of the file system.If you always set this variable toyes, it can take even more space:rebuilding every spkg would use double the amount of space, and anyupgrades to spkgs would create still more directories, using still morespace.

Note

In an existing Sage installation, runningsage-i-s<package-name>orsage-f-s<package-name> installs the spkg<package-name> andkeeps the corresponding build directory; thus settingSAGE_KEEP_BUILT_SPKGS toyes mimics this behavior whenbuilding Sage from scratch or when installing individual spkgs.So you can set this variable toyes instead of using the-s flagforsage-i andsage-f.

SAGE_FAT_BINARY¶

To build binaries that will run on thewidest range of target CPUs set this variable toyes beforebuilding Sage or configure with--enable-fat-binary.This does not make the binaries relocatable, it onlyavoids newer CPU instruction set extensions. For relocatable (=canbe moved to a different directory) binaries, you must usehttps://github.com/sagemath/binary-pkg

SAGE_SUDO¶

Set this tosudo-E or to any othercommand prefix that is necessary to write into a installationhierarchy (SAGE_LOCAL) owned by root or another user.Note that this command needs to preserve environment variablesettings (plainsudo does not).

Not all Sage packages currently supportSAGE_SUDO.

Therefore this environment variable is most useful when a systemadministrator wishes to install an additional Sage package thatsupportsSAGE_SUDO, into a root-owned installationhierarchy (SAGE_LOCAL).

Environment variables controlling the documentation build¶

SAGE_DOCBUILD_OPTS¶

The value of this variable is passed as anargument tosage--docbuildallhtml orsage--docbuildallpdf whenyou runmake,makedoc, ormakedoc-pdf. For example:

• add--no-plot to this variable to avoid building the graphics coming fromthe..PLOT directive within the documentation,

• add--no-preparsed-examples to only show the original Sage code of“EXAMPLES” blocks, suppressing the tab with the preparsed, plain Pythonversion, or

• add--include-tests-blocks to include all “TESTS” blocks in the referencemanual.

Runsage--docbuildhelp to see the full list of options.

SAGE_SPKG_INSTALL_DOCS¶

If set toyes, then installpackage-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 assumethat certain programs are available on the system (for example,latex orpdflatex).

SAGE_USE_CDNS¶

If set toyes, then build the documentationusing CDNs (Content Distribution Networks) for scripts necessary for HTMLdocumentation, such asMathJax.

SAGE_LIVE_DOC¶

If set toyes, then build live Sagedocumentation. If theMakelive button on any webpage of the live doc isclicked, every example code gets aCodeMirrorcode cell runnable viaThebe.Thebe is responsible in sending the code to the Sage computing environmentbuilt byBinder and showing the output result.The Sage computing environment can be specified to either a Binder repo or alocal Jupyter server. The environment variableSAGE_JUPYTER_SERVERis used for this purpose.

SAGE_JUPYTER_SERVER¶

Set this to eitherbinder,binder:repo withrepospecifying a Binder repo or the URL to a local Jupyter server.

• binder refers toSage’s official Binder repo. This is assumed if theenvironment variableSAGE_JUPYTER_SERVER is not set.

• binder:repo specifies a Binder repo withrepo, which is a GitHubrepository name, optionally added with a branch name with/ separator.

• To use a local Jupyter server instead of Binder, then set the URL toSAGE_JUPYTER_SERVER and the secret token to environment variableSAGE_JUPYTER_SERVER_TOKEN, which can be left unset if the defaulttokensecret is used. If the live doc was built withSAGE_JUPYTER_SERVER=http://localhost:8889, run a local Jupyter serverby

  ./sage--notebook=jupyterlab\--ServerApp.token='secret'\--ServerApp.allow_origin='null'\--ServerApp.disable_check_xsrf=true\--ServerApp.port=8889\--ServerApp.open_browser=false

  before opening the Sage documentation webpage.

Environment variables dealing with specific Sage packages¶

SAGE_MATPLOTLIB_GUI¶

If set to anything non-empty exceptno,then Sage will attempt to build the graphical backend when it builds thematplotlib package.

OPENBLAS_CONFIGURE¶

Adds additional configuration flags forthe OpenBLAS package that gets added to themake command. (seeIssue #23272)

PARI_CONFIGURE¶

Use this to pass extra parameters toPARI’sConfigure script, for example to specify graphicssupport (which is disabled by default). See the filebuild/pkgs/pari/spkg-install.in for more information.

SAGE_TUNE_PARI¶

If yes, enable PARI self-tuning. Note thatthis can be time-consuming. If you set this variable to “yes”, youwill also see this:WARNING:TuningPARI/GPisunreliable.YoumayfindyourbuildofPARIfails,orPARI/GPdoesnotworkproperlyoncebuilt.WerecommendtobuildthispackagewithSAGE_CHECK="yes".

PARI_MAKEFLAGS¶

The value of this variable is passed as anargument to the$MAKE command when compiling PARI.

Environment variables dealing with doctesting¶

SAGE_TIMEOUT¶

Used for Sage’s doctesting: the number of secondsto 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 ofseconds to allow a doctest before timing it out, if tests are run usingsage-t--long.If this isn’t set, the default is 1800 seconds (30 minutes).

SAGE_TEST_GLOBAL_ITER¶

SAGE_TEST_ITER¶

These canbe used instead of passing the flags--global-iterations and--file-iterations, respectively, tosage-t. Indeed, thesevariables are only used if the flags are unset. Runsage-t-hfor more information on the effects of these flags (and thereforethese variables).

Environment variables set within Sage environments¶

Sage sets some other environment variables. The most accurate way tosee what Sage does is to first runenv from a shell prompt to seewhat environment variables you have set. Then runsage--sh-cenv to see the list after Sage sets its variables. (This runs aseparate shell, executes the shell commandenv, and then exitsthat shell, so after running this, your settings will be restored.)Alternatively, you can peruse the shell scriptsrc/bin/sage-env.

Sage also has some environment-like settings. Some of these correspondto actual environment variables while others have names likeenvironment variables but are only available while Sage is running. Tosee a list, executesage.env.[TAB] while running Sage.

Caveats when upgrading system packages¶

When Sage has been installed from source, it will make use of various systempackages; in particular, it will link to shared libraries provided bythe system.

The system’s package manager does not keep track of the applications thatmake use of the shared libraries. Therefore indiscriminate upgrades ofsystem packages can break a Sage installation.

This can always be fixed by a full rebuild:

$makedistclean&&makebuild

But this time-consuming step can often be avoided by just reinstalling afew packages. The commandmake-jlist-broken-packages assists withthis:

$make-jlist-broken-packagesmake --no-print-directory auditwheel_or_delocate-no-deps...#Checking.../local/var/lib/sage/installed/bliss-0.73+debian-1+sage-2016-08-02.p0...Checking shared library file '.../local/lib/libumfpack.dylib'Checking shared library file '.../local/var/tmp/sage/build/suitesparse-5.10.1/src/lib/libsliplu.1.0.2.dylib'Error during installcheck of 'suitesparse': .../local/var/tmp/sage/build/suitesparse-5.10.1/src/lib/libsliplu.1.0.2.dylib...Uninstall broken packages by typing:    make lcalc-SAGE_LOCAL-uninstall;    make ratpoints-SAGE_LOCAL-uninstall;    make r-SAGE_LOCAL-uninstall;    make suitesparse-SAGE_LOCAL-uninstall;

After running the suggested commands, run:

$makebuild

Upgrading Sage using a separate git worktree¶

When you have a working installation of Sage built from source and wish totry out a new version, we strongly recommend to use a separategit worktree, so that youcan keep using your existing installation when something goes wrong.

Start from the directory created when you usedgitclone, perhaps~/sage/sage/. Let’s verify that this is indeed a git repository bylooking at the hidden.git subdirectory. It will looks like this,but the exact contents can vary:

[alice@localhost sage]$ls.gitCOMMIT_EDITMSG HEAD           branches       description    gitk.cacheindex          logs           packed-refs    FETCH_HEAD     ORIG_HEADconfig         hooks          info           objects        refs

Good. Now let’s see what worktrees already exist:

[alice@localhost sage]$gitworktreelist/home/alice/sage/sage                     c0ffeefe10 [master]

We see just one line, the directory created when you usedgitclone.We will call this the “main worktree” from now on. Next to the directory,you can see the abbreviated commit sha and the name of the branch thatwe’re on (master).

To try out a new version of Sage, let’s fetch it first from the mainrepository:

[alice@localhost sage]$gitfetchupstream10.3.beta8From https://github.com/sagemath/sage * tag                     10.3.beta8 -> FETCH_HEAD

Now let’s create a new worktree. We need a name for it; it shouldstart withworktree- but can be anything after that. Experienceshows that worktrees are often repurposed later, and because adirectory containing a Sage installation cannot be moved withoutbreaking the installation in it, it may be a good idea to choosea memorable name without much meaning:

[alice@localhost sage]$gitworktreeaddworktree-purpleFETCH_HEADPreparing worktree (detached HEAD 30b3d78fac)Updating files: 100% (11191/11191), done.HEAD is now at 30b3d78fac Updated SageMath version to 10.3.beta8

We now have a subdirectoryworktree-purple. This is a“linked worktree”:

[alice@localhost sage]$gitworktreelist/home/alice/sage/sage                     c0ffeefe10 [master]/home/alice/sage/sage/worktree-purple     30b3d78fac (detached HEAD)[alice@localhost sage]$cdworktree-purple[alice@localhost worktree-purple]$catVERSION.txtSageMath version 10.3.beta8, Release Date: 2024-02-13

All worktrees created in this way share the same repository,so they have access to all branches:

[alice@localhost worktree-purple]$git--no-pagerbranch-v* (no branch) 30b3d78fac Updated SageMath version to 10.3.beta8+ master      2a9a4267f9 Updated SageMath version to 10.2

In fact,.git here is not a directory, just a hiddenfile:

[alice@localhost worktree-purple]$ls-l.git-rw-r--r--  1 alice  staff  59 Feb 20 18:16 .git

In the new worktree, we now build Sage from scratch. Thisis completely independent of and will not disrupt yourexisting working installation in the main worktree.

We will refer again to the step-by-step instructionsfrom the fileREADME.md.Our worktreeworktree-purple is theSAGE_ROOTfor this purpose.

One thing that we can share between worktrees withoutworry is the directoryupstream, where Sage cachesdownloaded archives of packages. To have the new worktreeshare it with the main worktree, let’s create a symboliclink. This is an optional step that will avoidre-downloading files that you already have:

[alice@localhost worktree-purple]$ln-s../upstream/.

Now let’s build Sage, starting with the step:

[alice@localhost worktree-purple]$makeconfigure

Refer to the fileREADME.mdfor the following steps.