Python configuration files

To create the blank configuration files, run:

ipython profile create [profilename]

If you leave out the profile name, the files will be created for the default profile (see :ref:`profiles`). These will typically be located in :file:`~/.ipython/profile_default/`, and will be named :file:`ipython_config.py`, for historical reasons you may also find files named with IPython prefix instead of Jupyter: :file:`ipython_notebook_config.py`, etc. The settings in :file:`ipython_config.py` apply to all IPython commands.

By default, configuration files are fully featured Python scripts that can execute arbitrary code, the main usage is to set value on the configuration object c which exist in your configuration file.

You can then configure class attributes like this:

c.InteractiveShell.automagic = False

Be careful with spelling--incorrect names will simply be ignored, with no error.

To add to a collection which may have already been defined elsewhere or have default values, you can use methods like those found on lists, dicts and sets: append, extend, :meth:`~traitlets.config.LazyConfigValue.prepend` (like extend, but at the front), add and update (which works both for dicts and sets):

c.InteractiveShellApp.extensions.append('Cython')

# sample ipython_config.py

c.TerminalIPythonApp.display_banner = True
c.InteractiveShellApp.log_level = 20
c.InteractiveShellApp.extensions = [
    'myextension'
]
c.InteractiveShellApp.exec_lines = [
    'import numpy',
    'import scipy'
]
c.InteractiveShellApp.exec_files = [
    'mycode.py',
    'fancy.ipy'
]
c.InteractiveShell.colors = 'LightBG'
c.InteractiveShell.xmode = 'Context'
c.TerminalInteractiveShell.confirm_exit = False
c.TerminalInteractiveShell.editor = 'nano'

c.PrefilterManager.multi_line_specials = True

c.AliasManager.user_aliases = [
 ('la', 'ls -al')
]

JSON Configuration files

In case where executability of configuration can be problematic, or configurations need to be modified programmatically, IPython also support a limited set of functionalities via .json configuration files.

You can define most of the configuration options via a JSON object whose hierarchy represents the value you would normally set on the c object of .py configuration files. The following ipython_config.json file:

{
    "InteractiveShell": {
        "colors": "LightBG",
    },
    "InteractiveShellApp": {
        "extensions": [
            "myextension"
        ]
    },
    "TerminalInteractiveShell": {
        "editor": "nano"
    }
}

Is equivalent to the following ipython_config.py:

c.InteractiveShell.colors = 'LightBG'
c.InteractiveShellApp.extensions = [
    'myextension'
]
c.TerminalInteractiveShell.editor = 'nano'

Command line arguments

Every configurable value can be set from the command line, using this syntax:

ipython --ClassName.attribute=value

Many frequently used options have short aliases and flags, such as --matplotlib (to integrate with a matplotlib GUI event loop) or --pdb (automatic post-mortem debugging of exceptions).

To see all of these abbreviated options, run:

ipython --help
jupyter notebook --help
# etc.

Options specified at the command line, in either format, override options set in a configuration file.

The config magic

You can also modify config from inside IPython, using a magic command:

%config IPCompleter.greedy = True

At present, this only affects the current session - changes you make to config are not saved anywhere. Also, some options are only read when IPython starts, so they can't be changed like this.

Running IPython from Python

If you are using :ref:`embedding` to start IPython from a normal python file, you can set configuration options the same way as in a config file by creating a traitlets :class:`Config` object and passing it to start_ipython like in the example below.