Notebook

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. 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

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 have config=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] Generating default config file: '/home/takluyver/.ipython/profile_newprofile/ipython_config.py'
[ProfileCreate] Generating default config file: '/home/takluyver/.ipython/profile_newprofile/ipython_kernel_config.py'
[ProfileCreate] Generating default config file: '/home/takluyver/.ipython/profile_newprofile/ipython_console_config.py'
[ProfileCreate] Generating default config file: '/home/takluyver/.ipython/profile_newprofile/ipython_qtconsole_config.py'
[ProfileCreate] Generating default config file: '/home/takluyver/.ipython/profile_newprofile/ipython_notebook_config.py'
[ProfileCreate] Generating default config file: '/home/takluyver/.ipython/profile_newprofile/ipython_nbconvert_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

/home/takluyver/.ipython/profile_default
/home/takluyver/.ipython/profile_newprofile

You can skim

In [5]:

profile = get_ipython().profile_dir.location
profile

Out[5]:

'/home/takluyver/.ipython/profile_default'

In [6]:

ls $profile

db/                     ipython_nbconvert_config.py  nbconfig/      startup/
history.sqlite          ipython_notebook_config.py   notebook.json  static/
history.sqlite-journal  ipython_qtconsole_config.py  pid/
ipython_config.py       log/                         security/

Let's peek at our config file

In [7]:

pycat $profile/ipython_config.py

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 [8]:

!ls $profile/startup

imports.py  README

In [9]:

!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 [10]:

%%writefile $profile/startup/simpleimports.py

import sys, os, time, re

Writing /home/takluyver/.ipython/profile_default/startup/simpleimports.py

Restart the kernel and then run the following cells immediately to verify these scripts have been executed:

In [11]:

sys

Out[11]:

<module 'sys' (built-in)>

Defining your own magic¶

As we have seen already, IPython has cell and line magics. You can define your own magics using any Python function and the register_magic_function method:

In [12]:

from IPython.core.magic import (register_line_magic, register_cell_magic,
                                register_line_cell_magic)

In [13]:

@register_line_magic
def sleep(line):
    """A simple function for sleeping"""
    import time
    t = float(line)
    time.sleep(t)

In [14]:

%sleep 2

In [15]:

%sleep?

Cell Magic¶

Cell magics take two args:

the line on the same line of the magic
the cell the multiline body of the cell after the first line

In [16]:

@register_cell_magic
def dummy(line, cell):
    """dummy cell magic for displaying the line and cell it is passed"""
    print("line: %r" % line)
    print("cell: %r" % cell)

In [17]:

%%dummy this is the line
this
is the
cell

line: 'this is the line'
cell: 'this\nis the\ncell'

For more details on declaring your own magics in more complex scenarios, see our docs.