Configure and Start a Notebook Server

Configure and Start a Notebook Server

The NotebookObject is used to configure and launch a Sage Notebook server.

class sagenb.notebook.notebook_object.NotebookObject

Start the Sage Notebook server. More details about using these options, as well as tips and tricks, may be available at this Sage wiki page. If a notebook server is already running in the directory, this will open a browser to the running notebook.


  • directory – string; directory that contains the Sage notebook files; the default is .sage/sage_notebook.sagenb, in your home directory.

  • port – integer (default: 8080), port to serve the notebook on.

  • interface – string (default: 'localhost'), address of network interface to listen on; give '' to listen on all interfaces.

  • port_tries – integer (default: 0), number of additional ports to try if the first one doesn’t work (not implemented).

  • secure – boolean (default: False) if True use https so all communication, e.g., logins and passwords, between web browsers and the Sage notebook is encrypted via SSL. You must have OpenSSL installed to use this feature, or if you compile Sage yourself, have the OpenSSL development libraries installed. Highly recommended!

    When notebook() is run for first time with secure=True, it will generate new keys and store them to .sage/notebook/. Remove this when you want to generate new keys, for example if an older version of Sage has generated keys that are too short for current browsers.

  • reset – boolean (default: False) if True allows you to set the admin password. Use this if you forget your admin password.

  • accounts – boolean (default: False) if True, any visitor to the website will be able to create a new account. If False, only the admin can create accounts (currently, this can only be done by running with accounts=True and shutting down the server properly (SIG_INT or SIG_TERM), or on the command line with, e.g.,

    from sagenb.notebook.notebook import load_notebook
    nb = load_notebook("directory_to_run_sage_in")
    user_manager = nb.user_manager()
    user_manager.add_user("username", "password", "email@place", "user")
  • automatic_login – boolean (default: True) whether to pop up a web browser and automatically log into the server as admin. You can override the default browser by setting the SAGE_BROWSER environment variable, e.g., by putting

    export SAGE_BROWSER="firefox"

    in the file .bashrc in your home directory.

  • upload – string (default: None) Full path to a local file (sws, txt, zip) to be uploaded and turned into a worksheet(s). This is equivalent to manually uploading a file via http://localhost:8080/upload or to fetching http://localhost:8080/upload_worksheet?url=file:///... in a script except that (hopefully) you will already be logged in.


    If you are running a server for others to log into, set \(automatic_login=False\). Otherwise, all of the worksheets on the entire server will be loaded when the server automatically logs into the admin account.

  • timeout – integer (default: 0) seconds until idle worksheet sessions automatically timeout, i.e., the corresponding Sage session terminates. 0 means “never timeout”. If your server is running out of memory, setting a timeout can be useful as this will free the memory used by idle sessions.

  • doc_timeout – integer (default: 600) seconds until idle live documentation worksheet sessions automatically timeout, i.e., the corresponding Sage session terminates. 0 means “never timeout”.

  • server_pool – list of strings (default: None) list; this option specifies that worksheet processes run as a separate user (chosen from the list in the server_pool – see below).


If you have problems with the server certificate hostname not matching, do notebook.setup().


The require_login option has been removed. Use \(automatic_login\) to control automatic logins instead—\(automatic_login=False\) corresponds to \(require_login=True\).


  1. I just want to run the Sage notebook. Type:

  2. I want to run the Sage notebook server on a remote machine and be the only person allowed to log in. Type:

    notebook(interface='', secure=True)

    the first time you do this you’ll be prompted to set an administrator password. Use this to login. NOTE: You may have to run notebook.setup() again and change the hostname. ANOTHER NOTE: You must have installed pyOpenSSL in order to use secure mode; see the top-level Sage README file or the “Install from Source Code” section in the Sage manual for more information.

  3. I want to create a Sage notebook server that is open to anybody in the world to create new accounts. To run the Sage notebook publicly (1) at a minimum run it from a chroot jail or inside a virtual machine (see this Sage wiki page) and (2) use a command like:

    notebook(interface='', server_pool=['sage1@localhost'],
    ulimit='-v 500000', accounts=True, automatic_login=False)

    The server_pool option specifies that worksheet processes run as a separate user. The ulimit option restricts the memory available to each worksheet processes to 500 MB. See help on the accounts option above.

    Be sure that sage_notebook.sagenb/users.pickle and the contents of sage_notebook.sagenb/backups are chmod og-rwx, i.e., only readable by the notebook process, since otherwise any user can read users.pickle, which contains user email addresses and account information (passwords are stored hashed, so fewer worries there). You will need to use the directory option to accomplish this.

INPUT: (more advanced)

  • server_pool – list of strings (initial default: None), if given, should be a list like ['sage1@localhost‘, 'sage2@localhost‘], where you have setup ssh keys so that typing:

    ssh sage1@localhost

    logs in without requiring a password, e.g., by typing ssh-keygen as the notebook server user, then putting ~/.ssh/ as the file .ssh/authorized_keys. Note: you have to get the permissions of files and directories just right – see this Sage wiki page for more details.

    Files between the main Sage process and the server_pool workers are transferred through /tmp by default. If the environment variable SAGENB_TMPDIR or TMPDIR exists, that directory is used instead. This directory must be shared, so if the machines are separate the server machine must NFS-export /tmp or SAGENB_TMPDIR.

  • server – string (“twistd” (default) or “flask”). The server to use to server content.

  • profile – True, False, or file prefix (default: False - no profiling), If True, profiling is saved to a randomly-named file like \(sagenb-*-profile*.stats\) in the $DOT_SAGE directory. If a string, that string is used as a prefix for the pstats data file.

  • ulimit – string (initial default: None – leave as is), if given and server_pool is also given, the worksheet processes are run with these constraints. See the ulimit documentation. Common options include:

    • -t The maximum amount of cpu time in seconds. NOTE: For Sage, -t is the wall time, not cpu time.
    • -u The maximum number of processes available to a single user.
    • -v The maximum amount of virtual memory available to the process.

    Values are in 1024-byte increments, except for -t, which is in seconds, and -u which is a positive integer. Example: ulimit=”-v 400000 -t 30”


The values of server_pool and ulimit default to what they were last time the notebook command was called.


  • If you create a file $DOT_SAGE/notebook.css then it will get applied when rendering the notebook HTML. This allows notebook administrators to customize the look of the notebook. Note that by default $DOT_SAGE is $HOME/.sage.
notebook(directory=None, port=8080, interface='localhost', port_tries=50, secure=False, reset=False, accounts=None, openid=None, server_pool=None, ulimit='', timeout=None, doc_timeout=None, upload=None, automatic_login=True, start_path='', fork=False, quiet=False, server='twistd', profile=False, subnets=None, require_login=None, open_viewer=None, address=None)

x.__init__(...) initializes x; see help(type(x)) for signature


x.__init__(...) initializes x; see help(type(x)) for signature

sagenb.notebook.notebook_object.inotebook(*args, **kwds)

Exactly the same as notebook(...) but with secure=False.

sagenb.notebook.notebook_object.test_notebook(admin_passwd, secure=False, directory=None, port=8050, interface='localhost', verbose=False)

This function is used to test notebook server functions.


sage: from sagenb.notebook.notebook_object import test_notebook
sage: passwd = str(randint(1,1<<128))
sage: nb = test_notebook(passwd, interface='localhost', port=8060)
sage: import urllib
sage: h = urllib.urlopen('http://localhost:8060')
sage: homepage =
sage: h.close()
sage: 'html' in homepage
sage: nb.dispose()

Previous topic

The Sage Notebook

Next topic

Notebook Keybindings

This Page