IPython.core.magics.execution:ExecutionMagics.run

Extended Summary

Usage

%run [-n -i -e -G]
     [( -t [-N<N>] | -d [-b<N>] | -p [profile options] )]
     ( -m mod | filename ) [args]

The filename argument should be either a pure Python script (with extension .py), or a file with custom IPython syntax (such as magics). If the latter, the file can be either a script with .ipy extension, or a Jupyter notebook with .ipynb extension. When running a Jupyter notebook, the output from print statements and other displayed objects will appear in the terminal (even matplotlib figures will open, if a terminal-compliant backend is being used). Note that, at the system command line, the jupyter run command offers similar functionality for executing notebooks (albeit currently with some differences in supported options).

Parameters after the filename are passed as command-line arguments to the program (put in sys.argv). Then, control returns to IPython's prompt.

This is similar to running at a system prompt python file args, but with the advantage of giving you IPython's tracebacks, and of loading all variables into your interactive namespace for further use (unless -p is used, see below).

The file is executed in a namespace initially consisting only of __name__=='__main__' and sys.argv constructed as indicated. It thus sees its environment as if it were being run as a stand-alone program (except for sharing global objects such as previously imported modules). But after execution, the IPython interactive namespace gets updated with all variables defined in the program (except for __name__ and sys.argv). This allows for very convenient loading of code for interactive work, while giving each program a 'clean sheet' to run in.

Arguments are expanded using shell-like glob match. Patterns '', '?', '[seq]' and '[!seq]' can be used. Additionally, tilde '~' will be expanded into user's home directory. Unlike real shells, quotation does not suppress expansions. Use *two back slashes (e.g. \\*) to suppress expansions. To completely disable these expansions, you can use -G flag.

On Windows systems, the use of single quotes ' when specifying a file is not supported. Use double quotes ".

Options:

-n

__name__ is NOT set to '__main__', but to the running file's name without extension (as python does under import). This allows running scripts and reloading the definitions in them without calling code protected by an if __name__ == "__main__" clause.

-i

run the file in IPython's namespace instead of an empty one. This is useful if you are experimenting with code written in a text editor which depends on variables defined interactively.

-e

ignore sys.exit() calls or SystemExit exceptions in the script being run. This is particularly useful if IPython is being used to run unittests, which always exit with a sys.exit() call. In such cases you are interested in the output of the test results, not in seeing a traceback of the unittest module.

-t

print timing information at the end of the run. IPython will give you an estimated CPU time consumption for your script, which under Unix uses the resource module to avoid the wraparound problems of time.clock(). Under Unix, an estimate of time spent on system tasks is also given (for Windows platforms this is reported as 0.0).

If -t is given, an additional -N<N> option can be given, where <N> must be an integer indicating how many times you want the script to run. The final timing report will include total and per run results.

For example (testing the script myscript.py)

In [1]: run -t myscript

IPython CPU timings (estimated):
  User  :    0.19597 s.
  System:        0.0 s.

In [2]: run -t -N5 myscript

IPython CPU timings (estimated):
Total runs performed: 5
  Times :      Total       Per run
  User  :   0.910862 s,  0.1821724 s.
  System:        0.0 s,        0.0 s.

-d

run your program under the control of pdb, the Python debugger. This allows you to execute your program step by step, watch variables, etc. Internally, what IPython does is similar to calling

pdb.run('execfile("YOURFILENAME")')

with a breakpoint set on line 1 of your file. You can change the line number for this automatic breakpoint to be <N> by using the -bN option (where N must be an integer). For example

%run -d -b40 myscript

will set the first breakpoint at line 40 in myscript.py. Note that the first breakpoint must be set on a line which actually does something (not a comment or docstring) for it to stop execution.

Or you can specify a breakpoint in a different file

%run -d -b myotherfile.py:20 myscript

When the pdb debugger starts, you will see a (Pdb) prompt. You must first enter 'c' (without quotes) to start execution up to the first breakpoint.

Entering 'help' gives information about the use of the debugger. You can easily see pdb's full documentation with "import pdb;pdb.help()" at a prompt.

-p

run program under the control of the Python profiler module (which prints a detailed report of execution times, function calls, etc).

You can pass other options after -p which affect the behavior of the profiler itself. See the docs for %prun for details.

In this mode, the program's variables do NOT propagate back to the IPython interactive namespace (because they remain in the namespace where the profiler executes them).

Internally this triggers a call to %prun, see its documentation for details on the options available specifically for profiling.

There is one special usage for which the text above doesn't apply: if the filename ends with .ipy[nb], the file is run as ipython script, just as if the commands were written on IPython prompt.

-m

specify module name to load instead of script path. Similar to the -m option for the python interpreter. Use this option last if you want to combine with other %run options. Unlike the python interpreter only source modules are allowed no .pyc or .pyo files. For example

%run -m example

will run the example module.

-G

disable shell-like glob expansion of arguments.