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#
SageMath version 9.8, Release Date: 2023-02-11
Running Sage, the most common options:
file.[sage|py|spyx] -- run given .sage, .py or .spyx file
-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", and produce
the corresponding Python file
"file.sage.py"
-q -- quiet; start with no banner
--min -- do not populate global namespace
(must be first option)
--nodotsage -- run Sage without using the user's
.sage directory: create and use a temporary
.sage directory instead.
--gthread, --qthread, --q4thread, --wthread, --pylab
-- pass the option through to IPython
--simple-prompt -- pass the option through to IPython: use
this option with sage-shell mode in emacs
--gdb -- run Sage under the control of gdb
--lldb -- run Sage under the control of lldb
Running external programs:
--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
--gap3 [...] -- run Sage's Gap3 with the given arguments
(not installed currently, run sage -i gap3)
--git [...] -- run Sage's Git with the given arguments
--gp [...] -- run Sage's PARI/GP calculator with the
given arguments
--ipython [...], --ipython3 [...]
-- run Sage's IPython using the default
environment (not Sage), passing additional
additional options to IPython
--jupyter [...] -- run Sage's Jupyter with given arguments
--kash [...] -- run Sage's Kash with the given arguments
(not installed currently, run sage -i kash)
--M2 [...] -- run Sage's Macaulay2 with the given arguments
(not installed currently, run sage -i macaulay2)
--maxima [...] -- run Sage's Maxima with the given arguments
--mwrank [...] -- run Sage's mwrank with the given arguments
--pip [...] -- invoke pip, the Python package manager
--polymake [...] -- run Sage's Polymake with given arguments
(not installed currently, run sage -i polymake)
--python [...], --python3 [...]
-- run the Python 3 interpreter
-R [...] -- run Sage's R with the given arguments
--singular [...] -- run Sage's singular with the given arguments
--sqlite3 [...] -- run Sage's sqlite3 with given arguments
Running the notebook:
-n [...], --notebook=[...]
-- start the notebook; valid options include
'default', 'jupyter', 'jupyterlab', and 'export'.
Current default is 'jupyter'.
Run "sage --notebook --help" for more details.
Testing files:
-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
--all -- test all files
--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 block
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
--random-seed[=seed] -- random seed (integer) for fuzzing doctests
--new -- only test files modified since last commit
--initial -- only show the first failure per block
--debug -- drop into PDB after an unexpected error
--failed -- only test files that failed last test
--warn-long [timeout] -- warning if doctest is slow
--only-errors -- only output failures, not successes
--gc=GC -- control garbarge collection (ALWAYS:
collect garbage before every test; NEVER:
disable gc; DEFAULT: Python default)
--short[=secs] -- run as many doctests as possible in about 300
seconds (or the number of seconds given.) This runs
the tests for each module from the top of the file
and skips tests once it exceeds the budget
allocated for that file.
--help -- show all doctesting options
--tnew [...] -- equivalent to -t --new
-tp <N> [...] -- like -t above, but tests in parallel using
N threads, with 0 interpreted as min(8, cpu_count())
--testall [options] -- equivalent to -t --all
--coverage <files> -- give information about doctest coverage of files
--coverageall -- give summary info about doctest coverage of
all files in the Sage library
--startuptime [module] -- display how long each component of Sage takes to
start up; optionally specify a module to get more
details about that particular module
Some developer utilities:
--sh [...] -- run a shell with Sage environment variables
as they are set in the runtime of Sage
--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.)
File conversion:
--rst2ipynb [...] -- Generates Jupyter notebook (.ipynb) from standalone
reStructuredText source.
(not installed currently, run sage -i rst2ipynb)
--ipynb2rst [...] -- Generates a reStructuredText source file from
a Jupyter notebook (.ipynb).
--sws2rst <sws doc> -- Generates a reStructuredText source file from
a Sage worksheet (.sws) document.
(not installed currently, run sage -i sage_sws2rst)
Valgrind memory debugging:
--cachegrind -- run Sage using Valgrind's cachegrind tool. The log
files are named sage-cachegrind.PID can be found in
$DOT_SAGE
--callgrind -- run Sage using Valgrind's callgrind tool. The log
files are named sage-callgrind.PID can be found in
$DOT_SAGE
--massif -- run Sage using Valgrind's massif tool. The log
files are named sage-massif.PID can be found in
$DOT_SAGE
--memcheck -- run Sage using Valgrind's memcheck tool. The log
files are named sage-memcheck.PID can be found in
$DOT_SAGE
--omega -- run Sage using Valgrind's omega tool. The log
files are named sage-omega.PID can be found in
$DOT_SAGE
--valgrind -- this is an alias for --memcheck
Getting help:
-v, --version -- display Sage version information
--dumpversion -- print brief Sage version
-h, -?, --help -- print a short help message
--advanced -- list all command line options