Getting started with Sage


Sage Beginner's Guide

Sage Beginner's Guide

Unlock the full potential of Sage for simplifying and automating mathematical computing

        Read more about this book      

(For more resources related to this topic, see here.)

Remember that you don't actually have to install Sage to start using it. You can start learning Sage by utilizing one of the free public notebook servers that can be found at However, if you find that Sage suits your needs, you will want to install a copy on your own computer. This will guarantee that Sage is always available to you, and it will reduce the load on the public servers so that others can experiment with Sage. In addition, your data will be more secure, and you can utilize more computing power to solve larger problems.


Before you begin

At the moment, Sage is fully supported on certain versions of the following platforms: some Linux distributions (Fedora, openSUSE, Red Hat, and Ubuntu), Mac OS X, OpenSolaris, and Solaris. Sage is tested on all of these platforms before each release, and binaries are always available for these platforms. The latest list of supported platforms is available at The page also contains information about platforms that Sage will probably run on, and the status of efforts to port Sage to various platforms.

When downloading Sage, the website attempts to detect which operating system you are using, and directs you to the appropriate download page. If it sends you to the wrong download page, use the "Download" menu at the top of the page to choose the correct platform. If you get stuck at any point, the official Sage installation guide is available at


Installing a binary version of Sage on Windows

Installing Sage on Windows is slightly more involved than installing a typical Windows program. Sage is a collection of over 90 different tools. Many of these tools are developed within a UNIX-like environment, and some have not been successfully ported to Windows. Porting programs from UNIX-like environments to Windows requires the installation of Cygwin (, which provides many of the tools that are standard on a Linux system. Rather than attempting to port all of the necessary tools to Cygwin on Windows, the developers of Sage have chosen to distribute Sage as a virtual machine that can run on Windows with the use of the free VMWare Player. A port to Cygwin is in progress, and more information can be found at

Downloading VMware Player

The VMWare Player can be found at Clicking the Download link will direct you to a registration form. Fill out and submit the form. You will receive a confirmation email that contains a link that must be clicked to complete the registration process and take you to the download page. Choose Start Download Manager, which downloads and runs a small application that performs the actual download and saves the file to a location of your choice.

Installing VMWare Player

After downloading VMWare Player, double-click the saved file to start the installation wizard. Follow the instructions in the wizard to install the Player. You will have to reboot the computer when instructed.

Downloading and extracting Sage

Download Sage by following the Download link from The site should automatically detect that you are using Windows, and direct you to the right download page. Choose the closest mirror and download the compressed virtual machine. Be aware that the file is nearly 1GB in size. Once the download is complete, right-click the compressed file and choose Extract all from the pop-up menu.

Launching the virtual machine

Launch VMware Player and accept the license terms. When the Player has started, click Open a Virtual Machine and select the Sage virtual machine, which is called sage-vmware.vmx. Click Play virtual machine to run Sage. If you have run Sage before, it should appear in the list of virtual machines on the left side of the dialog box, and you can double-click to run it.

Sage Beginner's Guide

When the virtual machine launches, you may receive one or more warnings about various devices (such as Bluetooth adapters) that the virtual machine cannot connect to. Don't worry about this, since Sage doesn't need these devices.

Start Sage

Sage Beginner's Guide

Once the virtual machine is running, you will see three icons. Double-clicking the Sage Notebook icon starts the Sage notebook interface, while the Sage icon starts the commandline interface. The first time you run Sage, you will have to wait while it regenerates files. When it finishes, you are ready to go.

You may get the warning "External network not set up" when launching the notebook interface. This does not cause any problems.

Sage Beginner's Guide

When you are done using Sage, choose Shut Down… from the System menu at the top of the window, and a dialog will appear. Click the Shut Down button to close the virtual machine.

Sage Beginner's Guide


Installing a binary version of Sage on OS X

On Mac OS X, you have the option of installing a pre-built binary application, or downloading the source code and compiling Sage yourself. One advantage of the pre-built binary is that it is very easy to install, because it contains everything you need to run Sage. Another advantage of the binary is that building Sage from source requires a lot of computational resources, and may take a long time on older machines. However, there are a number of disadvantages to prebuilt binaries. The binary download is quite large, and the installed files take up a lot of disk space. Many of the tools in the binary may be duplicates of tools you already have on your system. Pre-built binaries cannot be tuned to take advantage of the hardware features of a particular platform, so building Sage from source is preferred if you are looking for the best performance on CPU-intensive tasks. You will have to choose which method is right for you.

Downloading Sage

Download Sage by following the Download link from The site should automatically detect that you are using OS X, and direct you to the right download page. Choose a mirror site close to you. Select your architecture (Intel for new Macs, or PowerPC for older G4 and G5 macs). Then, click the link for the correct .dmg file for you version of Mac OS X. If you aren't sure, click the Apple menu on the far left side of the menu bar and choose About This Mac.

Installing Sage

Once the download is complete, double-click the .dmg file to mount the disk image. Drag the Sage folder from the disk image to the desired location on your hard drive (such as the Apps folder).

If the copy procedure fails, you will need to do it from the command line. Open the Terminal application and enter the following commands. Be sure to change the name sage-4.5-OSX-64bit-10.6-i386-Darwin.dmg to the name of the file you just downloaded:

$ cd /Applications
$ cp -R -P /Volumes/sage-4.5-OSX-64bit-10.6-i386-Darwin.dmg /sage .

After the copy process is complete, right-click on the icon for the disk image, and choose Eject.

Starting Sage

Use the Finder to visit the Sage folder that you just created. Double-click on the icon called Sage. It should open with the Terminal application. If it doesn't start, right-click on the icon, go to the Open With submenu and choose The Sage command line will now be running in a Terminal window. The first time you run Sage, you will have to wait while it regenerates files. When it finishes, you are ready to go.

Sage Beginner's Guide

There are three ways to exit Sage: type exit or quit at the Sage command prompt, or press Ctrl-D in the Terminal window. You can then quit the Terminal application.



        Read more about this book      

(For more resources related to this topic, see here.)


Installing a binary version of Sage on GNU/Linux

As with Mac OS X, you have the option of installing a pre-built binary application for your version of Linux, or downloading the source code and compiling Sage yourself. The same trade-offs apply to Linux. Keep in mind that the Sage team only distributes pre-build binaries for a few popular distributions. If you are using a different distribution, you'll have to compile Sage from source anyway. The following instructions will assume you are downloading a binary application. I will use Ubuntu as an example, but other versions of Linux should be very similar.

Most modern Linux distributions use a package manager to install and remove software. Sage is not available as an officially supported package for any Linux distribution at this time. "Unofficial" packages have been created for Debian, Mandriva, Ubuntu, and possibly others, but they are unlikely to be up to date and may not work properly. An effort to integrate Sage with Gentoo Linux can be found at

Downloading and decompressing Sage

Download the appropriate pre-built binary from Choose the closest mirror, and then choose the appropriate architecture for your operating system. If you're not sure whether your operating system is built for 32 or 64 bit operation, open a terminal and type the following on the command line:

$ uname -m

If the output contains 64, then your system is probably a 64-bit system. If not, it's a 32-bit. An alternative way to check is with the following command:

$ file /usr/bin/bin

If the file type contains 64, your kernel probably supports 64 bit applications. If not, you need the 32 bit version. Select the appropriate prebuilt binary and save it to your computer.

Once the download is done, uncompress the archive. You can use the graphical archiving tool for your version of Linux (the Ubuntu archiver is shown in the following screenshot). If you prefer the command line, type the following:

tar --lzma -xvf sage-*...tar.lzma

Sage Beginner's Guide

Running Sage from your user account

After decompression, you will have a single directory. This directory is self-contained, so no further installation is necessary. You can simply move it to a convenient location within your home directory. This is a good option if you don't have administrator privileges on the system, or if you are the only person who uses the system. To run Sage, open a terminal and change to the Sage directory (you will have to modify the command below, depending on the version you installed and where you installed it):

cfinch@ubuntu:$ cd sage-4.5.3-linux-32bit-ubuntu_10.04_lts-i686-Linux

Run Sage by typing the following:

cfinch@ubuntu:$ ./sage

Don't forget the period before the slash! The first time you run Sage, you will have to wait while it regenerates files, as shown in the following screenshot. When it finishes, you are ready to go.

Sage Beginner's Guide

There are three ways to exit Sage: type exit or quit at the Sage command prompt, or press Ctrl-D in the terminal window.

Installing for multiple users

If you are the administrator of a shared system, you may want to install Sage so that everyone can use it. Since Sage consists of one self-contained directory, I suggest moving it to the /opt directory:

sudo mv sage-4.5.3-linux-32bit-ubuntu_10.04_lts-i686-Linux /opt
[sudo] password for cfinch:

To make it easy for everyone to run Sage, make a symbolic link from /usr/bin to the actual location:

cfinch@ubuntu:/usr/bin$ sudo ln -s /opt/sage-4.5.3-linux-32bitubuntu_
10.04_lts-i686-Linux/sage sage
[sudo] password for cfinch:

As before, Sage will have to regenerate its internal files the first time it runs after moving. You should run Sage once as a user with administrative privileges, because other users won't have the necessary write permissions to save the files. Once this is completed, any user will be able to use Sage by typing Sage at the command prompt.


Building Sage from source

This section will describe how to build Sage from source code on OS X or Linux. Although Sage consists of nearly 100 packages, the build process hides much of the complexity. It is impossible to provide instructions for all of the platforms that can build Sage, but the following guidelines should cover most cases. The official documentation for building Sage from source is available at


In order to compile Sage, you will need about 2.5GB of free disk space, and the following tools must be installed:

  • GCC
  • g++
  • gfortran
  • make
  • m4
  • perl
  • ranlib
  • tar
  • readline and its development headers
  • ssh-keygen (only needed to run the notebook in secure mode)
  • latex (highly recommended, though not strictly required)

If you are running OS X (version 10.4 or later), install XCode to get all of these tools. XCode is available for free when you sign up as a developer at Make sure that you have XCode version 2.4 or later.

If you are running Linux, use your package manager to install any missing tools. For example, on a Debian-based system like Ubuntu, run the following on the command line:

$ sudo apt-get install build-essential m4 gfortran
$ sudo apt-get install readline-common libreadline-dev

To install LaTeX (optional):

$ sudo apt-get install texlive xpdf evince xdvi

Downloading and decompressing source tarball

Download the latest source tarball from Open a terminal, change to the directory where you saved the tarball, and decompress it with the following command:

$ tar -xvf sage-*.tar

Building Sage

If you have a multi-core or multi-processor machine, you can speed up the build process by performing a parallel compilation. You can control this by setting the MAKE environment variable. For example, using Bash syntax, you can set the MAKE variable to use four cores:

$ export MAKE="make -j4"

Change to the Sage directory:

$ cd sage-*

Build Sage:

$ make

Sage may take a long time (1 hour to several days) to compile, depending on the speed of the machine.


When the compilation process is done, you should be able to run Sage from the build directory. If you want to move the Sage installation or make it available to other users on a shared Linux system, follow the directions in the previous sections.


At this point, you should have a functioning Sage installation on your machine. In this article we covered how to install a binary version of Sage on Windows and install a binary version of Sage on OS X; install a binary version of Sage on GNU/Linux; compile Sage from source.

Further resources on this subject:

You've been reading an excerpt of:

Sage Beginner's Guide

Explore Title