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 10.0, Release Date: 2023-05-20

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