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.7, Release Date: 2022-09-19

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
  --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
  --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
  --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
  --tox [options] <files|dirs> -- general entry point for testing
                                  and linting of the Sage library
     -e <envlist>     -- run specific test environments
                         (default: run all except full pycodestyle)
        doctest                -- run the Sage doctester 
                                  (same as "sage -t")
        coverage               -- give information about doctest coverage of files 
                                  (same as "sage --coverage[all]")
        startuptime            -- display how long each component of Sage takes to start up 
                                  (same as "sage --startuptime")
        pycodestyle-minimal    -- check against Sage's minimal style conventions
        relint                 -- check whether some forbidden patterns appear 
                                  (includes all patchbot pattern-exclusion plugins)
        codespell              -- check for misspelled words in source code
        rst                    -- validate Python docstrings markup as reStructuredText
        pyright                -- run the static typing checker pyright
        pycodestyle            -- check against the Python style conventions of PEP8
     -p auto          -- run test environments in parallel
     --help           -- show tox help
  --pytest [options] <files|dirs> -- run pytest on the Sage library
     --help           -- show pytest help

Some developer utilities:

  --grep [options] <string>
                      -- regular expression search through the Sage
                         library for "string". Any options will
                         get passed to the "grep" command.
  --grepdoc [options] <string>
                      -- regular expression search through the
                         Sage documentation for "string".
  --search_src ...    -- same as --grep
  --search_doc ...    -- same as --grepdoc
  --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

Building the Sage library:

  -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.
  -br                 -- build and run Sage

  -bt [...]           -- build Sage and test; same options as -t
  -btp <N> [...]      -- build Sage and test in parallel; same options as -tp
  -btnew [...]        -- build Sage and test modified files, as in -t --new

  -bn [...], --build-and-notebook [...]
                      -- build the Sage library (as by running "sage -b")
                         and then start the notebook

Package handling:

  --package [args]    -- call the package manager with given arguments.
                         Run without arguments for help.
  --experimental      -- list all experimental packages that can be installed
  -i [opts] [pkgs]    -- install the given Sage packages.  Options:
                           -c -- run the packages' test suites,
                                 overriding the settings of
                                 SAGE_CHECK and SAGE_CHECK_PACKAGES
                           -d -- only download, do not install packages
                           -f -- force build: install the packages even
                                 if they are already installed
                           -s -- do not delete the temporary build directories
                                 after a successful build
                           -y -- reply yes to prompts about experimental
                                 and old-style packages; warning: there
                                 is no guarantee that these packages will
                                 build correctly; use at your own risk
                           -n -- reply no to prompts about experimental
                                 and old-style packages
  -f [opts] [pkgs]    -- shortcut for -i -f: force build of the given Sage
                         packages
  -p [opts] [packages]-- install the given Sage packages, without dependency
                         checking. Options are the same as for the -i command.
  --optional          -- list all optional packages that can be installed
  --standard          -- list all standard packages that can be installed
  --installed         -- list all installed packages

Making Sage distributions:

  --sdist             -- build a source distribution of Sage

Building the documentation:

  --docbuild [lang/]<document> <html|pdf|...> -- Build the Sage documentation

Other developer tools:

  --root              -- print the Sage root directory
  --git-branch        -- print the current git branch
  --buildsh [...]     -- run a shell with Sage environment variables
                         as they are set while building Sage and its packages