Configuring IPython¶
Finding configuration options¶
IPython has many configurable attributes. These can be viewed using the -h flag to the command line applications:
In [1]:
!ipython -h
=========
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. For Linux users,
IPYTHONDIR defaults to `$HOME/.config/ipython`, and for other Unix systems
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
profile
Create and manage IPython profiles.
console
Launch the IPython terminal-based Console.
kernel
Start a kernel without an attached frontend.
notebook
Launch the IPython HTML Notebook Server.
nbconvert
Convert notebooks to/from other formats.
qtconsole
Launch the IPython Qt Console.
history
Manage the IPython history database.
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'.
--no-autoindent
Turn off autoindenting.
--autoedit-syntax
Turn on auto editing of files with syntax errors.
--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()].
--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.
--pylab
Pre-load matplotlib and numpy for interactive use with
the default matplotlib backend.
--matplotlib
Configure matplotlib for interactive use with
the default matplotlib backend.
--term-title
Enable auto setting the terminal title.
--classic
Gives IPython a similar feel to the classic Python prompt.
--autoindent
Turn on autoindenting.
--no-automagic
Turn off the auto calling of magic commands.
--banner
Display a banner upon starting IPython.
--automagic
Turn on the auto calling of magic commands. Type %%magic at the
IPython prompt for more information.
--no-deep-reload
Disable deep (recursive) reloading by default.
--no-term-title
Disable auto setting the terminal title.
--nosep
Eliminate all spacing between prompts.
-i
If running code from the command line, become interactive afterwards.
Note: can also be given simply as '-i.'
--debug
set log level to logging.DEBUG (maximize logging output)
--pprint
Enable auto pretty printing of results.
--no-autoedit-syntax
Turn off auto editing of files with syntax errors.
--quiet
set log level to logging.CRITICAL (minimize logging output)
--no-color-info
Disable using colors for info related things.
--color-info
IPython can display information about objects via a set of func-
tions, and optionally can use colors for this, syntax highlighting
source code and various other elements. However, because this
information is passed through a pager (like 'less') and many pagers get
confused with color codes, this option is off by default. You can test
it and turn it on permanently in your ipython_config.py file if it
works for you. Test it and turn it on permanently if it works with
your system. The magic function %%color_info allows you to toggle this
interactively for testing.
--init
Initialize profile with default config files. This is equivalent
to running `ipython profile create <profile>` prior to startup.
--no-pdb
Disable auto calling the pdb debugger after every exception.
--quick
Enable quick startup with no config files.
--no-confirm-exit
Don't prompt the user when exiting.
--pydb
Use the third party 'pydb' package as debugger, instead of pdb.
Requires that pydb is installed.
--pdb
Enable auto calling the pdb debugger after every exception.
--no-pprint
Disable auto pretty printing of results.
--no-banner
Don't display a banner upon starting IPython.
--profile=<Unicode> (BaseIPythonApplication.profile)
Default: u'default'
The IPython profile to use.
--pylab=<CaselessStrEnum> (InteractiveShellApp.pylab)
Default: None
Choices: ['auto', 'gtk', 'inline', 'osx', 'qt', 'qt4', 'tk', 'wx']
Pre-load matplotlib and numpy for interactive use, selecting a particular
matplotlib backend and loop integration.
--matplotlib=<CaselessStrEnum> (InteractiveShellApp.matplotlib)
Default: None
Choices: ['auto', 'gtk', 'inline', 'osx', 'qt', 'qt4', 'tk', 'wx']
Configure matplotlib for interactive use with the default matplotlib
backend.
--colors=<CaselessStrEnum> (InteractiveShell.colors)
Default: 'LightBG'
Choices: ('NoColor', 'LightBG', 'Linux')
Set the color scheme (NoColor, Linux, or LightBG).
--cache-size=<Integer> (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
--logfile=<Unicode> (InteractiveShell.logfile)
Default: ''
The name of the logfile to use.
--profile-dir=<Unicode> (ProfileDir.location)
Default: u''
Set the profile location directly. This overrides the logic used by the
`profile` option.
-c <Unicode> (InteractiveShellApp.code_to_run)
Default: ''
Execute the given command string.
--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).
--ipython-dir=<Unicode> (BaseIPythonApplication.ipython_dir)
Default: u'/Users/minrk/.ipython'
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 options can also be specified through the
environment variable IPYTHONDIR.
--gui=<CaselessStrEnum> (InteractiveShellApp.gui)
Default: None
Choices: ('qt', 'wx', 'gtk', 'glut', 'pyglet', 'osx')
Enable GUI event loop integration ('qt', 'wx', 'gtk', 'glut', 'pyglet',
'osx').
--logappend=<Unicode> (InteractiveShell.logappend)
Default: ''
Start logging to the given file in append mode.
-m <Unicode> (InteractiveShellApp.module_to_run)
Default: ''
Run the module as a script.
--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.
--ext=<Unicode> (InteractiveShellApp.extra_extension)
Default: ''
dotted module name of an IPython extension to load.
--config=<Unicode> (BaseIPythonApplication.extra_config_file)
Default: u''
Path to an extra config file to load.
If specified, load this config file in addition to any other IPython config.
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 nbconvert # convert notebooks to/from other formats
This is an important trick for finding out configuration info:
$> ipython [subcommand] --help-all | grep [-C context] PATTERN
--help-all exposes everything configurable in IPython,
there is a good chance you will find what you are looking for.
A common configuration question is:
how do I disable the "Do you really want to exit" message when quitting with
Ctrl-d?
Well, logically this has to do with exit, so let's look for it:
In [2]:
!ipython --help-all | GREP_COLOR='1;31;46' grep --color exit
If invoked with no options, it executes the file and exits, passing the IPython session after running the script, rather than exiting. Files ending --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. --no-confirm-exit Don't prompt the user when exiting. --TerminalInteractiveShell.confirm_exit=<CBool> 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.
Which shows me that I can disable the confirmation for a single IPython session with
$> ipython --no-confirm-exit
or I can set the TerminalInteractiveShell.confirm_exit=False in a config file,
to have it be the default behavior.
Configuration principles¶
Here are the design principles of the IPython configuration system:
- Configuration is always done using class attributes
- Classes that have configurable attributes are subclasses of
Configurable - Attributes that are configurable are typed traitlets objects (
Bool,Unicode, etc.) that haveconfig=True - In config files, configurable attributes can be set using the format
Class.attr_name=the_value - At the command line, configurable attributes can be set using the syntax
--Class.attr_name=the_value - At the command line, some attributes have shorthands of the form
--attr-name=value - Values set at the command line have higher priority than those set in config files
The IPython Profile¶
IPython has a notion of 'profiles' - these are directories that live in your IPYTHONDIR, which contain configuration and runtime information.
Let's create the default profile
In [3]:
!ipython profile create newprofile
[ProfileCreate] WARNING | Generating default config file: u'/Users/minrk/.ipython/profile_newprofile/ipython_config.py' [ProfileCreate] WARNING | Generating default config file: u'/Users/minrk/.ipython/profile_newprofile/ipython_qtconsole_config.py' [ProfileCreate] WARNING | Generating default config file: u'/Users/minrk/.ipython/profile_newprofile/ipython_notebook_config.py'
This creates a profile in your IPYTHONDIR (ipython locate is a quick way to see where your IPYTHONDIR is),
and populates it with automatically generated default config files.
In [4]:
!ipython locate profile default
!ipython locate profile newprofile
/Users/minrk/.ipython/profile_default /Users/minrk/.ipython/profile_newprofile
You can skim
In [5]:
profile = get_ipython().profile_dir.location
profile
Out[5]:
u'/Users/minrk/Dropbox/dev/ip/pres/ipython-in-depth/profile_euroscipy'
In [6]:
ls $profile
db/ ipython_config.py ipython_qtconsole_config.py pid/ startup/ history.sqlite ipython_notebook_config.py log/ security/ static/
Let's peek at our config file
In [7]:
pycat $profile/ipython_config.py
The %config magic¶
The %config magic lets you do some configuration at runtime, rather than in configuration files.
In [8]:
%matplotlib inline
%config with no arguments will show you what configurable objects exist:
In [9]:
%config
Available objects for config:
ZMQInteractiveShell
HistoryManager
PrefilterManager
AliasManager
IPCompleter
PromptManager
DisplayFormatter
LaTeXTool
MagicsManager
IPKernelApp
StoreMagics
InlineBackend
And %config Class will show you the config for that class:
In [10]:
%config InlineBackend
InlineBackend options
-------------------
InlineBackend.close_figures=<Bool>
Current: True
Close all figures at the end of each cell.
When True, ensures that each cell starts with no active figures, but it also
means that one must keep track of references in order to edit or redraw
figures in subsequent cells. This mode is ideal for the notebook, where
residual plots from other cells might be surprising.
When False, one must call figure() to create new figures. This means that
gcf() and getfigs() can reference figures created in other cells, and the
active figure can continue to be edited with pylab/pyplot methods that
reference the current active figure. This mode facilitates iterative editing
of figures, and behaves most consistently with other matplotlib backends,
but figure barriers between cells must be explicit.
InlineBackend.figure_format=<CaselessStrEnum>
Current: 'retina'
Choices: ['svg', 'png', 'retina']
The image format for figures with the inline backend.
InlineBackend.rc=<Dict>
Current: {'font.size': 10, 'figure.figsize': (6.0, 4.0), 'figure.facecolor': 'white', 'savefig.dpi': 72, 'figure.subplot.bottom': 0.125, 'figure.edgecolor': 'white'}
Subset of matplotlib rcParams that should be different for the inline
backend.
Most importantly, the %config magic can be used to change the value of a configurable attribute at runtime. Here we tell the inline matplotlib backend to use SVG instead of the default PNG
In [11]:
import numpy as np
import matplotlib.pyplot as plt
x = np.linspace(0,10,1000)
y = np.sin(x)
plt.plot(x,y)
Out[11]:
[<matplotlib.lines.Line2D at 0x107a74090>]
In [12]:
%config InlineBackend.figure_format = 'svg'
In [13]:
plt.plot(x,y)
Out[13]:
[<matplotlib.lines.Line2D at 0x107b1d9d0>]
Startup Files¶
Startup files are simple Python or IPython scripts that are run whenever you start IPython. These are a useful way to do super common imports, or for building database connections to load on startup of a non-default profile.
We can use a startup file to ensure that our %tic/toc magics are always defined,
every time we start IPython.
In [14]:
!ls $profile/startup
README
In [15]:
!cat $profile/startup/README
This is the IPython startup directory
.py and .ipy files in this directory will be run *prior* to any code or files specified
via the exec_lines or exec_files configurables whenever you load this profile.
Files will be run in lexicographical order, so you can control the execution order of files
with a prefix, e.g.::
00-first.py
50-middle.py
99-last.ipy
Adding common imports, so we never have to forget them again
In [16]:
%%writefile $profile/startup/simpleimports.py
import sys, os, time, re
Writing /Users/minrk/Dropbox/dev/ip/pres/ipython-in-depth/profile_euroscipy/startup/simpleimports.py
Restart the kernel and then run the following cells immediately to verify these scripts have been executed:
In [1]:
sys
Out[1]:
<module 'sys' (built-in)>
Extensions¶
In [2]:
profile = get_ipython().profile_dir.location
In [3]:
!cat $profile/ipython_config.py | grep InteractiveShellApp.extensions
# c.InteractiveShellApp.extensions = []
In [4]:
!echo "c.InteractiveShellApp.extensions = ['mymagics']" >> $profile/ipython_config.py
!tail $profile/ipython_config.py
# If you want to add script magics that aren't on your path, specify them in
# script_paths
# c.ScriptMagics.script_magics = []
# Dict mapping short 'ruby' names to full paths, such as '/opt/secret/bin/ruby'
#
# Only necessary for items in script_magics where the default path will not find
# the right interpreter.
# c.ScriptMagics.script_paths = {}
c.InteractiveShellApp.extensions = ['mymagics']
Restart the kernel to see the effects:
In [1]:
import time
%tic
time.sleep(0.1)
%toc
101 ms
In [2]:
%nbrun Sample
hello
