config.rst
148 lines
| 5.9 KiB
| text/x-rst
|
RstLexer
|
r2277 | .. _config_overview: | ||
============================================ | ||||
Overview of the IPython configuration system | ||||
============================================ | ||||
|
r21385 | This section describes the IPython configuration system. This is based on | ||
:mod:`traitlets.config`; see that documentation for more information | ||||
about the overall architecture. | ||||
|
r3351 | |||
|
r2277 | Configuration file location | ||
=========================== | ||||
|
r4040 | So where should you put your configuration files? IPython uses "profiles" for | ||
configuration, and by default, all profiles will be stored in the so called | ||||
"IPython directory". The location of this directory is determined by the | ||||
following algorithm: | ||||
|
r2277 | |||
|
r7089 | * If the ``ipython-dir`` command line flag is given, its value is used. | ||
|
r2277 | |||
|
r21385 | * If not, the value returned by :func:`IPython.paths.get_ipython_dir` | ||
|
r6696 | is used. This function will first look at the :envvar:`IPYTHONDIR` | ||
|
r13417 | environment variable and then default to :file:`~/.ipython`. | ||
|
r6701 | Historical support for the :envvar:`IPYTHON_DIR` environment variable will | ||
be removed in a future release. | ||||
|
r3351 | |||
|
r13417 | For most users, the configuration directory will be :file:`~/.ipython`. | ||
Previous versions of IPython on Linux would use the XDG config directory, | ||||
creating :file:`~/.config/ipython` by default. We have decided to go | ||||
back to :file:`~/.ipython` for consistency among systems. IPython will | ||||
issue a warning if it finds the XDG location, and will move it to the new | ||||
location if there isn't already a directory there. | ||||
|
r2277 | |||
|
r4040 | Once the location of the IPython directory has been determined, you need to know | ||
which profile you are using. For users with a single configuration, this will | ||||
simply be 'default', and will be located in | ||||
|
r6696 | :file:`<IPYTHONDIR>/profile_default`. | ||
|
r4040 | |||
The next thing you need to know is what to call your configuration file. The | ||||
basic idea is that each application has its own default configuration filename. | ||||
The default named used by the :command:`ipython` command line program is | ||||
:file:`ipython_config.py`, and *all* IPython applications will use this file. | ||||
Other applications, such as the parallel :command:`ipcluster` scripts or the | ||||
QtConsole will load their own config files *after* :file:`ipython_config.py`. To | ||||
load a particular configuration file instead of the default, the name can be | ||||
overridden by the ``config_file`` command line flag. | ||||
To generate the default configuration files, do:: | ||||
|
r11984 | $ ipython profile create | ||
|
r4040 | |||
and you will have a default :file:`ipython_config.py` in your IPython directory | ||||
under :file:`profile_default`. If you want the default config files for the | ||||
:mod:`IPython.parallel` applications, add ``--parallel`` to the end of the | ||||
command-line args. | ||||
|
r2277 | |||
|
r7089 | |||
Locating these files | ||||
-------------------- | ||||
From the command-line, you can quickly locate the IPYTHONDIR or a specific | ||||
profile with: | ||||
.. sourcecode:: bash | ||||
|
r11984 | $ ipython locate | ||
|
r7089 | /home/you/.ipython | ||
|
r11984 | $ ipython locate profile foo | ||
|
r7089 | /home/you/.ipython/profile_foo | ||
These map to the utility functions: :func:`IPython.utils.path.get_ipython_dir` | ||||
and :func:`IPython.utils.path.locate_profile` respectively. | ||||
|
r13492 | .. _profiles_dev: | ||
|
r2277 | |||
Profiles | ||||
======== | ||||
|
r4040 | A profile is a directory containing configuration and runtime files, such as | ||
logs, connection info for the parallel apps, and your IPython command history. | ||||
The idea is that users often want to maintain a set of configuration files for | ||||
different purposes: one for doing numerical computing with NumPy and SciPy and | ||||
another for doing symbolic computing with SymPy. Profiles make it easy to keep a | ||||
separate configuration files, logs, and histories for each of these purposes. | ||||
|
r2277 | |||
Let's start by showing how a profile is used: | ||||
.. code-block:: bash | ||||
|
r4198 | $ ipython --profile=sympy | ||
|
r2277 | |||
|
r4040 | This tells the :command:`ipython` command line program to get its configuration | ||
from the "sympy" profile. The file names for various profiles do not change. The | ||||
only difference is that profiles are named in a special way. In the case above, | ||||
|
r6696 | the "sympy" profile means looking for :file:`ipython_config.py` in :file:`<IPYTHONDIR>/profile_sympy`. | ||
|
r4040 | |||
The general pattern is this: simply create a new profile with: | ||||
.. code-block:: bash | ||||
|
r11984 | $ ipython profile create <name> | ||
|
r4040 | |||
which adds a directory called ``profile_<name>`` to your IPython directory. Then | ||||
|
r4198 | you can load this profile by adding ``--profile=<name>`` to your command line | ||
|
r4040 | options. Profiles are supported by all IPython applications. | ||
IPython ships with some sample profiles in :file:`IPython/config/profile`. If | ||||
you create profiles with the name of one of our shipped profiles, these config | ||||
files will be copied over instead of starting with the automatically generated | ||||
config files. | ||||
|
r21385 | IPython extends the config loader for Python files so that you can inherit | ||
config from another profile. To do this, use a line like this in your Python | ||||
config file: | ||||
.. sourcecode:: python | ||||
load_subconfig('ipython_config.py', profile='default') | ||||
|
r5248 | Security Files | ||
-------------- | ||||
If you are using the notebook, qtconsole, or parallel code, IPython stores | ||||
connection information in small JSON files in the active profile's security | ||||
directory. This directory is made private, so only you can see the files inside. If | ||||
you need to move connection files around to other computers, this is where they will | ||||
be. If you want your code to be able to open security files by name, we have a | ||||
convenience function :func:`IPython.utils.path.get_security_file`, which will return | ||||
the absolute path to a security file from its filename and [optionally] profile | ||||
name. | ||||
|
r9244 | .. _startup_files: | ||
|
r5248 | Startup Files | ||
------------- | ||||
|
r11983 | If you want some code to be run at the beginning of every IPython session with | ||
a particular profile, the easiest way is to add Python (``.py``) or | ||||
IPython (``.ipy``) scripts to your :file:`<profile>/startup` directory. Files | ||||
in this directory will always be executed as soon as the IPython shell is | ||||
constructed, and before any other code or scripts you have specified. If you | ||||
have multiple files in the startup directory, they will be run in | ||||
lexicographical order, so you can control the ordering by adding a '00-' | ||||
prefix. | ||||