##// END OF EJS Templates
DOC: minor fix
Matthias Geier -
Show More
@@ -1,132 +1,133 b''
1 1 .. _config_overview:
2 2
3 3 ============================================
4 4 Overview of the IPython configuration system
5 5 ============================================
6 6
7 7 This section describes the IPython configuration system. This is based on
8 8 :mod:`traitlets.config`; see that documentation for more information
9 9 about the overall architecture.
10 10
11 11 Configuration file location
12 12 ===========================
13 13
14 14 So where should you put your configuration files? IPython uses "profiles" for
15 15 configuration, and by default, all profiles will be stored in the so called
16 16 "IPython directory". The location of this directory is determined by the
17 17 following algorithm:
18 18
19 19 * If the ``ipython-dir`` command line flag is given, its value is used.
20 20
21 21 * If not, the value returned by :func:`IPython.paths.get_ipython_dir`
22 22 is used. This function will first look at the :envvar:`IPYTHONDIR`
23 23 environment variable and then default to :file:`~/.ipython`.
24 24 Historical support for the :envvar:`IPYTHON_DIR` environment variable will
25 25 be removed in a future release.
26 26
27 27 For most users, the configuration directory will be :file:`~/.ipython`.
28 28
29 29 Previous versions of IPython on Linux would use the XDG config directory,
30 30 creating :file:`~/.config/ipython` by default. We have decided to go
31 31 back to :file:`~/.ipython` for consistency among systems. IPython will
32 32 issue a warning if it finds the XDG location, and will move it to the new
33 33 location if there isn't already a directory there.
34 34
35 35 Once the location of the IPython directory has been determined, you need to know
36 36 which profile you are using. For users with a single configuration, this will
37 simply be 'default', and will be located in
37 simply be 'default', and will be located in
38 38 :file:`<IPYTHONDIR>/profile_default`.
39 39
40 40 The next thing you need to know is what to call your configuration file. The
41 41 basic idea is that each application has its own default configuration filename.
42 42 The default named used by the :command:`ipython` command line program is
43 43 :file:`ipython_config.py`, and *all* IPython applications will use this file.
44 44 The IPython kernel will load its own config file *after*
45 45 :file:`ipython_config.py`. To load a particular configuration file instead of
46 46 the default, the name can be overridden by the ``config_file`` command line
47 47 flag.
48 48
49 49 To generate the default configuration files, do::
50 50
51 51 $ ipython profile create
52 52
53 53 and you will have a default :file:`ipython_config.py` in your IPython directory
54 54 under :file:`profile_default`.
55
55 56 .. note::
56 57
57 58 IPython configuration options are case sensitive, and IPython cannot
58 59 catch misnamed keys or invalid values.
59 60
60 61 By default IPython will also ignore any invalid configuration files.
61 62
62 63 .. versionadded:: 5.0
63 64
64 65 IPython can be configured to abort in case of invalid configuration file.
65 66 To do so set the environment variable ``IPYTHON_SUPPRESS_CONFIG_ERRORS`` to
66 67 `'1'` or `'true'`
67 68
68 69
69 70 Locating these files
70 71 --------------------
71 72
72 73 From the command-line, you can quickly locate the IPYTHONDIR or a specific
73 74 profile with:
74 75
75 76 .. sourcecode:: bash
76 77
77 78 $ ipython locate
78 79 /home/you/.ipython
79 80
80 81 $ ipython locate profile foo
81 82 /home/you/.ipython/profile_foo
82 83
83 84 These map to the utility functions: :func:`IPython.utils.path.get_ipython_dir`
84 85 and :func:`IPython.utils.path.locate_profile` respectively.
85 86
86 87
87 88 .. _profiles_dev:
88 89
89 90 Profiles
90 91 ========
91 92
92 93 A profile is a directory containing configuration and runtime files, such as
93 94 logs, connection info for the parallel apps, and your IPython command history.
94 95
95 96 The idea is that users often want to maintain a set of configuration files for
96 97 different purposes: one for doing numerical computing with NumPy and SciPy and
97 98 another for doing symbolic computing with SymPy. Profiles make it easy to keep a
98 99 separate configuration files, logs, and histories for each of these purposes.
99 100
100 101 Let's start by showing how a profile is used:
101 102
102 103 .. code-block:: bash
103 104
104 105 $ ipython --profile=sympy
105 106
106 107 This tells the :command:`ipython` command line program to get its configuration
107 108 from the "sympy" profile. The file names for various profiles do not change. The
108 109 only difference is that profiles are named in a special way. In the case above,
109 110 the "sympy" profile means looking for :file:`ipython_config.py` in :file:`<IPYTHONDIR>/profile_sympy`.
110 111
111 112 The general pattern is this: simply create a new profile with:
112 113
113 114 .. code-block:: bash
114 115
115 116 $ ipython profile create <name>
116 117
117 118 which adds a directory called ``profile_<name>`` to your IPython directory. Then
118 119 you can load this profile by adding ``--profile=<name>`` to your command line
119 120 options. Profiles are supported by all IPython applications.
120 121
121 122 IPython ships with some sample profiles in :file:`IPython/config/profile`. If
122 123 you create profiles with the name of one of our shipped profiles, these config
123 124 files will be copied over instead of starting with the automatically generated
124 125 config files.
125 126
126 127 IPython extends the config loader for Python files so that you can inherit
127 128 config from another profile. To do this, use a line like this in your Python
128 129 config file:
129 130
130 131 .. sourcecode:: python
131 132
132 133 load_subconfig('ipython_config.py', profile='default')
General Comments 0
You need to be logged in to leave comments. Login now