=========
IPython
=========
Tools for Interactive Computing in Python
=========================================
A Python shell with automatic history (input and output), dynamic object
introspection, easier configuration, command completion, access to the
system shell and more. IPython can also be embedded in running programs.
Usage
ipython [subcommand] [options] [-c cmd | -m mod | file] [--] [arg] ...
If invoked with no options, it executes the file and exits, passing the
remaining arguments to the script, just as if you had specified the same
command with python. You may need to specify `--` before args to be passed
to the script, to prevent IPython from attempting to parse them. If you
specify the option `-i` before the filename, it will enter an interactive
IPython session after running the script, rather than exiting. Files ending
in .py will be treated as normal Python, but files ending in .ipy can
contain special IPython syntax (magic commands, shell expansions, etc.).
Almost all configuration in IPython is available via the command-line. Do
`ipython --help-all` to see all available options. For persistent
configuration, look into your `ipython_config.py` configuration file for
details.
This file is typically installed in the `IPYTHONDIR` directory, and there
is a separate configuration directory for each profile. The default profile
directory will be located in $IPYTHONDIR/profile_default. IPYTHONDIR
defaults to to `$HOME/.ipython`. For Windows users, $HOME resolves to
C:\Documents and Settings\YourUserName in most instances.
To initialize a profile with the default configuration file, do::
$> ipython profile create
and start editing `IPYTHONDIR/profile_default/ipython_config.py`
In IPython's documentation, we will refer to this directory as
`IPYTHONDIR`, you can change its default location by creating an
environment variable with this name and setting it to the desired path.
For more information, see the manual available in HTML and PDF in your
installation, or online at http://ipython.org/documentation.html.
Subcommands
-----------
Subcommands are launched as `ipython cmd [args]`. For information on using
subcommand 'cmd', do: `ipython cmd -h`.
locate
print the path to the IPython dir
trust
Sign notebooks to trust their potentially unsafe contents at load.
install-nbextension
Install IPython notebook extension files
kernel
Start a kernel without an attached frontend.
kernelspec
Manage IPython kernel specifications.
console
Launch the IPython terminal-based Console.
nbconvert
Convert notebooks to/from other formats.
profile
Create and manage IPython profiles.
notebook
Launch the IPython HTML Notebook Server.
history
Manage the IPython history database.
qtconsole
Launch the IPython Qt Console.
Options
-------
Arguments that take values are actually convenience aliases to full
Configurables, whose aliases are listed on the help line. For more information
on full configurables, see '--help-all'.
--nosep
Eliminate all spacing between prompts.
--quiet
set log level to logging.CRITICAL (minimize logging output)
--term-title
Enable auto setting the terminal title.
--pylab
Pre-load matplotlib and numpy for interactive use with
the default matplotlib backend.
--init
Initialize profile with default config files. This is equivalent
to running `ipython profile create <profile>` prior to startup.
--pydb
Use the third party 'pydb' package as debugger, instead of pdb.
Requires that pydb is installed.
--no-autoedit-syntax
Turn off auto editing of files with syntax errors.
--classic
Gives IPython a similar feel to the classic Python prompt.
--no-term-title
Disable auto setting the terminal title.
--no-banner
Don't display a banner upon starting IPython.
--no-automagic
Turn off the auto calling of magic commands.
--autoindent
Turn on autoindenting.
--no-deep-reload
Disable deep (recursive) reloading by default.
--matplotlib
Configure matplotlib for interactive use with
the default matplotlib backend.
--debug
set log level to logging.DEBUG (maximize logging output)
--autoedit-syntax
Turn on auto editing of files with syntax errors.
--no-color-info
Disable using colors for info related things.
--no-pprint
Disable auto pretty printing of results.
--banner
Display a banner upon starting IPython.
--no-confirm-exit
Don't prompt the user when exiting.
--pdb
Enable auto calling the pdb debugger after every exception.
--color-info
IPython can display information about objects via a set of functions,
and optionally can use colors for this, syntax highlighting
source code and various other elements. This is on by default, but can cause
problems with some pagers. If you see such problems, you can disable the
colours.
--no-pdb
Disable auto calling the pdb debugger after every exception.
--quick
Enable quick startup with no config files.
--deep-reload
Enable deep (recursive) reloading by default. IPython can use the
deep_reload module which reloads changes in modules recursively (it
replaces the reload() function, so you don't need to change anything to
use it). deep_reload() forces a full reload of modules whose code may
have changed, which the default reload() function does not. When
deep_reload is off, IPython will use the normal reload(), but
deep_reload will still be available as dreload(). This feature is off
by default [which means that you have both normal reload() and
dreload()].
--no-autoindent
Turn off autoindenting.
--automagic
Turn on the auto calling of magic commands. Type %%magic at the
IPython prompt for more information.
-i
If running code from the command line, become interactive afterwards.
--pprint
Enable auto pretty printing of results.
--confirm-exit
Set to confirm when you try to exit IPython with an EOF (Control-D
in Unix, Control-Z/Enter in Windows). By typing 'exit' or 'quit',
you can force a direct exit without any confirmation.
--config=<Unicode> (BaseIPythonApplication.extra_config_file)
Default: ''
Path to an extra config file to load.
If specified, load this config file in addition to any other IPython config.
--pylab=<CaselessStrEnum> (InteractiveShellApp.pylab)
Default: None
Choices: ['auto', 'gtk', 'gtk3', 'inline', 'nbagg', 'notebook', 'osx', 'qt', 'qt4', 'qt5', 'tk', 'wx']
Pre-load matplotlib and numpy for interactive use, selecting a particular
matplotlib backend and loop integration.
-c <Unicode> (InteractiveShellApp.code_to_run)
Default: ''
Execute the given command string.
--log-level=<Enum> (Application.log_level)
Default: 30
Choices: (0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL')
Set the log level by value or name.
--ipython-dir=<Unicode> (BaseIPythonApplication.ipython_dir)
Default: ''
The name of the IPython directory. This directory is used for logging
configuration (through profiles), history storage, etc. The default is
usually $HOME/.ipython. This option can also be specified through the
environment variable IPYTHONDIR.
--colors=<CaselessStrEnum> (InteractiveShell.colors)
Default: 'Linux'
Choices: ('NoColor', 'LightBG', 'Linux')
Set the color scheme (NoColor, Linux, or LightBG).
--matplotlib=<CaselessStrEnum> (InteractiveShellApp.matplotlib)
Default: None
Choices: ['auto', 'gtk', 'gtk3', 'inline', 'nbagg', 'notebook', 'osx', 'qt', 'qt4', 'qt5', 'tk', 'wx']
Configure matplotlib for interactive use with the default matplotlib
backend.
-m <Unicode> (InteractiveShellApp.module_to_run)
Default: ''
Run the module as a script.
--logfile=<Unicode> (InteractiveShell.logfile)
Default: ''
The name of the logfile to use.
--ext=<Unicode> (InteractiveShellApp.extra_extension)
Default: ''
dotted module name of an IPython extension to load.
--profile=<Unicode> (BaseIPythonApplication.profile)
Default: 'default'
The IPython profile to use.
--logappend=<Unicode> (InteractiveShell.logappend)
Default: ''
Start logging to the given file in append mode.
--cache-size=<Int> (InteractiveShell.cache_size)
Default: 1000
Set the size of the output cache. The default is 1000, you can change it
permanently in your config file. Setting it to 0 completely disables the
caching system, and the minimum value accepted is 20 (if you provide a value
less than 20, it is reset to 0 and a warning is issued). This limit is
defined because otherwise you'll spend more time re-flushing a too small
cache than working
--autocall=<Enum> (InteractiveShell.autocall)
Default: 0
Choices: (0, 1, 2)
Make IPython automatically call any callable object even if you didn't type
explicit parentheses. For example, 'str 43' becomes 'str(43)' automatically.
The value can be '0' to disable the feature, '1' for 'smart' autocall, where
it is not applied if there are no more arguments on the line, and '2' for
'full' autocall, where all callable objects are automatically called (even
if no arguments are present).
--gui=<CaselessStrEnum> (InteractiveShellApp.gui)
Default: None
Choices: ('glut', 'gtk', 'gtk3', 'osx', 'pyglet', 'qt', 'qt5', 'tk', 'wx')
Enable GUI event loop integration with any of ('glut', 'gtk', 'gtk3', 'osx',
'pyglet', 'qt', 'qt5', 'tk', 'wx').
--profile-dir=<Unicode> (ProfileDir.location)
Default: ''
Set the profile location directly. This overrides the logic used by the
`profile` option.
To see all available configurables, use `--help-all`
Examples
--------
ipython --matplotlib # enable matplotlib integration
ipython --matplotlib=qt # enable matplotlib integration with qt4 backend
ipython --log-level=DEBUG # set logging to DEBUG
ipython --profile=foo # start with profile foo
ipython qtconsole # start the qtconsole GUI application
ipython help qtconsole # show the help for the qtconsole subcmd
ipython console # start the terminal-based console application
ipython help console # show the help for the console subcmd
ipython notebook # start the IPython notebook
ipython help notebook # show the help for the notebook subcmd
ipython profile create foo # create profile foo w/ default config files
ipython help profile # show the help for the profile subcmd
ipython locate # print the path to the IPython directory
ipython locate profile foo # print the path to the directory for profile `foo`
ipython nbconvert # convert notebooks to/from other formats