Invoking Sage

To run Sage, you basically just need to type sage from the command-line prompt to start the Sage interpreter. See the Sage Installation Guide for information about making sure your $PATH is set correctly, etc.

Command-line options for Sage

Running Sage, the most common options

• file.[sage|py|spyx] – run the given .sage, .py or .spyx files (as in sage my_file.sage)
• -h, -?, --help – print a short help message
• -v, --version – print the Sage version
• --advanced – print (essentially this) list of Sage options
• -c cmd – evaluate cmd as sage code. For example, sage -c 'print factor(35)' will print “5 * 7”.

Running Sage, other options

• --preparse file.sage – preparse file.sage, a file of Sage code, and produce the corresponding Python file file.sage.py. See the Sage tutorial for more about preparsing and the differences between Sage and Python.
• -q – quiet; start with no banner
• --grep [options] <string> – grep through all the Sage library code for string. Any options will get passed to the “grep” command; for example, sage --grep -i epstein will search for epstein, and the -i flag tells grep to ignore case when searching. Note that while running Sage, you can also use the function search_src to accomplish the same thing.
• --grepdoc [options] <string> – grep through all the Sage documentation for string. Note that while running Sage, you can also use the function search_doc to accomplish the same thing.
• --min [...] – do not populate global namespace (must be first option)
• -gthread, -qthread, -q4thread, -wthread, -pylab – pass the option through to IPython
• --nodotsage – run Sage without using the user’s .sage directory: create and use a temporary .sage directory instead. Warning: notebooks are stored in the .sage directory, so any notebooks created while running with --nodotsage will be temporary also.

Running the notebook

• -n, --notebook – start the Sage notebook, passing all remaining arguments to the ‘notebook’ command in Sage
• -bn [...], --build-and-notebook [...] – build the Sage library (as by running sage -b) then start the Sage notebook
• --inotebook [...] – start the insecure Sage notebook

Running external programs and utilities

• --cython [...] – run Cython with the given arguments
• --ecl [...], --lisp [...] – run Sage’s copy of ECL (Embeddable Common Lisp) with the given arguments
• --gap [...] – run Sage’s Gap with the given arguments
• --git [...] – run Sage’s Git with the given arguments
• --gp [...] – run Sage’s PARI/GP calculator with the given arguments
• --ipython [...] – run Sage’s IPython using the default environment (not Sage), passing additional options to IPython
• --kash [...] – run Sage’s Kash with the given arguments
• --M2 [...] – run Sage’s Macaulay2 with the given arguments
• --maxima [...] – run Sage’s Maxima with the given arguments
• --mwrank [...] – run Sage’s mwrank with the given arguments
• --python [...] – run the Python interpreter
• -R [...] – run Sage’s R with the given arguments
• --scons [...] – run Sage’s scons
• --singular [...] – run Sage’s singular with the given arguments
• --twistd [...] – run Twisted server
• --sh [...] – run a shell with Sage environment variables set
• --gdb – run Sage under the control of gdb
• --gdb-ipython – run Sage’s IPython under the control of gdb
• --cleaner – run the Sage cleaner. This cleans up after Sage, removing temporary directories and spawned processes. (This gets run by Sage automatically, so it is usually not necessary to run it separately.)

Installing packages and upgrading

• -i [options] [packages] – install the given Sage packages (unless they are already installed); if no packages are given, print a list of all installed packages. Options:
  • -c – run the packages’ test suites, overriding the settings of SAGE_CHECK and SAGE_CHECK_PACKAGES.
  • -f – force build: install the packages even if they are already installed.
  • -s – do not delete the spkg/build directories after a successful build – useful for debugging.
• -f [options] [packages] – shortcut for -i -f: force build of the given Sage packages.
• --info [packages] – display the SPKG.txt file of the given Sage packages.
• --standard – list all standard packages that can be installed
• --optional – list all optional packages that can be installed
• --experimental – list all experimental packages that can be installed
• --upgrade [url] – download, build and install standard packages from given url. If url not given, automatically selects a suitable mirror. If url=’ask’, it lets you select the mirror.

Building and testing the Sage library

• --root – print the Sage root directory
• -b – build Sage library – do this if you have modified any source code files in $SAGE_ROOT/src/sage/.
• -ba – same as -b, but rebuild all Cython code. This could take a while, so you will be asked if you want to proceed.
• -ba-force – same as -ba, but don’t query before rebuilding
• --br – build and run Sage
• -t [options] <files|dir> – test examples in .py, .pyx, .sage or .tex files. Options:
  • --long – include lines with the phrase ‘long time’
  • --verbose – print debugging output during the test
  • --optional – also test all examples labeled # optional
  • --only-optional[=tags] – if no tags are specified, only run blocks of tests containing a line labeled # optional. If a comma separated list of tags is specified, only run blocks containing a line labeled # optional tag for any of the tags given and in these blocks only run the lines which are unlabeled or labeled #optional or labeled #optional tag for any of the tags given.
  • --randorder[=seed] – randomize order of tests
• -tnew [...] – like -t above, but only tests files modified since last commit
• -tp <N> [...] – like -t above, but tests in parallel using N threads with 0 interpreted as minimum(8, cpu_count())
• --testall [options] – test all source files, docs, and examples; options are the same as for -t.
• -bt [...] – build and test, options like -t above
• -btp <N> [...] – build and test in parallel, options like -tp above
• -btnew [...] – build and test modified files, options like -tnew
• --fixdoctests file.py [output_file] [--long] – writes a new version of file.py to output_file (default: file.py.out) that will pass the doctests. With the optional --long argument the long time tests are also checked. A patch for the new file is printed to stdout.
• --startuptime [module] – display how long each component of Sage takes to start up. Optionally specify a module (e.g., “sage.rings.qqbar”) to get more details about that particular module.
• --coverage <files> – give information about doctest coverage of files
• --coverageall – give summary info about doctest coverage of all files in the Sage library

Documentation

• --docbuild [options] document (format | command) – build or return information about the Sage documentation.

  • document – name of the document to build
  • format – document output format
  • command – document-specific command

  A document and either a format or a command are required, unless a list of one or more of these is requested.

  Options:

  • help, -h, --help – print a help message
  • -H, --help-all – print an extended help message, including the output from the options -h, -D, -F, -C all, and a short list of examples.
  • -D, --documents – list all available documents
  • -F, --formats – list all output formats
  • -C DOC, --commands=DOC – list all commands for document DOC; use -C all to list all
  • -i, --inherited – include inherited members in reference manual; may be slow, may fail for PDF output
  • -u, --underscore – include variables prefixed with _ in reference manual; may be slow, may fail for PDF output
  • -j, --jsmath – render math using jsMath; formats: html, json, pickle, web
  • --no-pdf-links – do not include PDF links in document website; formats: html, json, pickle, web
  • --check-nested – check picklability of nested classes in document reference
  • -N, --no-colors – do not color output; does not affect children
  • -q, --quiet – work quietly; same as --verbose=0
  • -v LEVEL, --verbose=LEVEL – report progress at level 0 (quiet), 1 (normal), 2 (info), or 3 (debug); does not affect children

  Advanced – use these options with care:

  • -S OPTS, --sphinx-opts=OPTS – pass comma-separated OPTS to sphinx-build
  • -U, --update-mtimes – before building reference manual, update modification times for auto-generated ReST files

Making Sage packages or distributions

• --pkg dir – create the Sage package dir.spkg from the directory dir
• --pkg_nc dir – as --pkg, but do not compress the package
• --merge – run Sage’s automatic merge and test script
• --bdist VER – build a binary distribution of Sage, with version VER
• --sdist – build a source distribution of Sage

Valgrind memory debugging

• --cachegrind – run Sage using Valgrind’s cachegrind tool
• --callgrind – run Sage using Valgrind’s callgrind tool
• --massif – run Sage using Valgrind’s massif tool
• --memcheck – run Sage using Valgrind’s memcheck tool
• --omega – run Sage using Valgrind’s omega tool
• --valgrind – this is an alias for --memcheck