sage-mode /

Filename Size Date modified Message
41 B
Ignore .DS_Store files
1.1 KB
Added tag sage-mode-0.14 for changeset 8cc5464d39d8
18.0 KB
Add COPYING and update SPKG.txt.
6.0 KB
Documented last change
580 B
Added sanity check for sage-mode-version
7.1 KB
Include note about sage-shell-mode in readme
1.5 KB
Use sage-native-execute to run Emacs since libraries might conflict with Sage's

Introduction to sage-mode

You might also be interested in sage-shell-mode, a completely independent package for interacting with Sagemath. See the Sagemath wiki for a comparison.

Installation and setup

There are three possibilities for installing sage-mode:

Option 1. Use the sage-mode bundled with Sage

This is the easiest. Since the spkg is already installed, you only need to activate it in Sage and in Emacs. For the former, run

sage -f sage_mode

For the latter, then somewhere in your .emacs add the following

(add-to-list 'load-path "$INSTALL_DIR")
(require 'sage "sage")
(setq sage-command "$SAGE_ROOT/sage")

where $INSTALL_DIR and $SAGE_ROOT have been replaced with the respective paths on you machine. $INSTALL_DIR refers to the directory of the sage-mode Emacs files: these are usually located in


Furthermore, if you would like typesetting of Sage results, consider customizing sage-view-default-commands and adding the following lines to your .emacs (after requiring sage):

(add-hook 'sage-startup-after-prompt-hook 'sage-view)

Also consider running (customize-group 'sage) in Emacs to see more options.

Option 2. Download a pre-compiled spkg at the sage-mode Bitbucket repository

Once you have downloaded the spkg for the version you want, you install the spkg in Sage by running

sage -f sage_mode_<version>.spkg

where sage_mode_<version>.spkg refers to the file you have downloaded.

You can then follow the remaining steps of Option 1 to install sage-mode in Emacs.

Option 3. Download the newest code from the Bitbucket repository.

The most cutting edge solution is to clone the Bitbucket repository: first, make sure you have an installation of Mercurial. Then in an appropriate directory, run

 hg clone

Then you can either create and install an spkg, or simply point Emacs at the directory, by adding something like the following to your .emacs:

(add-to-list 'load-path "/path/to/sage-mode/emacs/")
(require 'sage "sage")

To create an spkg, go to the sage-mode folder that you checked out, and run


where instead of $VERSION, you write a version number. The version "number" can be anything. It might be useful for later reference to use as $VERSION something which can identify the exaxt version you built, such as the hash of the latest commit (found with hg id -i -r .).

In any case, this creates a file sage_mode_<version>.spkg. You can then follow the steps in Option 2 as if you had downloaded this spkg from the repository.

The inferior sage shell

The primary element of sage-mode is interaction with a Sage shell in a buffer. Run the function sage in Emacs to start it. The new buffer communicates directly with a Sage shell in the background and behaves very much like it. You just type and send the command with <Enter>:

sage: 2+2
sage: x^2 + 1
x^2 + 1

If you activated sage-view in the setup, the last output line should be properly typeset with LaTeX. This already then beats running the Sage shell in a usual terminal; however, we are just getting started.

The shell also behaves like an Emacs shell:

  • Pressing M-p or C-up goes through earlier input.
  • The history of the shell is earlier in the buffer, and you can move around just as in any Emacs buffer. When you're not at the bottom command line, the text you enter won't send anything to the shell.
  • Pressing <Enter> on some line earlier in the buffer runs that line at the command line and returns the pointer there.
  • Pressing C-q C-j inserts a literal newline.

Of course, you also have access to tab-completion and the usual Sage help:

  • <Tab> at the command line attempts completion of current word. It understands all Sage and Python functions currently in scope, and it also completes attributes of objects. As usual in Emacs, with multiple suggestions they are presented in another window.
  • Adding ? after a name or attribute and then <Tab> shows the documentation for it in another window. Pressing <Enter> instead of <Tab> prints the documentation in the shell.
  • Adding ?? and then <Enter> prints the preceding object's source in the shell. TODO: /jsrn: This behaves as above when I do it, but when iandrus does it, it opens the source file. Why?

You can type quit to kill the Sage shell, or you can kill the entire buffer.

Editing your Sage code

Most of your code you will want to structure properly and keep, and so will naturally be edited in separate files and not typed directly into the Sage shell. When opening a .sage-file, sage-mode will be activated, providing you with syntax highlighting and various interaction with the Sage shell.

If you already have an open Sage shell, the newly opened file should be aware of it. If not, you can open a new shell with the sage function. Now you have various functions for sending code to the shell:

  • sage-send-buffer or C-c C-c sends the entire buffer's contents to the shell.
  • sage-send-defun or C-c C-d sends the def that the pointer is currently standing in.
  • sage-send-region or C-c C-r sends the currently marked region.
  • sage-attach-this-file will attach this file to the Sage shell, so that every time you execute something in the shell, that file will be reloaded if it has changed.

There are a few more such functions; type C-h m for a summary. Note that these functions are not exactly the same as typing in the shell: in particular, the result of the last line of code is not printed.

Of course, many .sage-files can be attached to the same shell, allowing for quick editing and reloading of your various sources. There is a pitfall here, though: after modifying a function or class, it is necessary to reload all functions, classes and objects referring to it, so that the Sage shell is not using the old definition. Sometimes it is easier or even necessary to restart the Sage shell in order to achieve this.

If you later restart the Sage shell, you might need to make buffers with .sage-files aware of the new shell. This is most easily done by revisiting the file: C-x C-v <Enter>.

Custom initialisation of Sage

Perhaps you would like to have Sage initialise with custom code when run from inside Emacs. As usual, you can use $HOME/.sage/sage.init for code which should run immediately after Sage starts. To run code only when Sage is run from inside Emacs is then done simply by guarding the code based on the environment variable $EMACS:

import os
if 'EMACS' in os.environ and os.environ['EMACS']:
    <Custom initialisation code goes here>