##// END OF EJS Templates
document ipython and ipykernel global configuration
Matthias Bussonnier -
Show More
@@ -1,165 +1,233 b''
1 1 =====================================
2 2 Introduction to IPython configuration
3 3 =====================================
4 4
5 5 .. _setting_config:
6 6
7 7 Setting configurable options
8 8 ============================
9 9
10 10 Many of IPython's classes have configurable attributes (see
11 11 :doc:`options/index` for the list). These can be
12 12 configured in several ways.
13 13
14 14 Python config files
15 15 -------------------
16 16
17 17 To create the blank config files, run::
18 18
19 19 ipython profile create [profilename]
20 20
21 21 If you leave out the profile name, the files will be created for the
22 ``default`` profile (see :ref:`profiles`). These will typically be
23 located in :file:`~/.ipython/profile_default/`, and will be named
24 :file:`ipython_config.py`, :file:`ipython_notebook_config.py`, etc.
25 The settings in :file:`ipython_config.py` apply to all IPython commands.
22 ``default`` profile (see :ref:`profiles`). These will typically be located in
23 :file:`~/.ipython/profile_default/`, and will be named
24 :file:`ipython_config.py`, for hitorical reasons you may also find fiels
25 named with IPytho nprefix instead of Jupyter:
26 :file:`ipython_notebook_config.py`, etc. The settings in
27 :file:`ipython_config.py` apply to all IPython commands.
26 28
27 The files typically start by getting the root config object::
28
29 c = get_config()
29 by default, configuration files are fully featured Python scripts that can
30 execute arbitrary code, the main usage is to set value on the config object
31 ``c`` which exist in your configuration file.
30 32
31 33 You can then configure class attributes like this::
32 34
33 35 c.InteractiveShell.automagic = False
34 36
35 37 Be careful with spelling--incorrect names will simply be ignored, with
36 38 no error.
37 39
38 To add to a collection which may have already been defined elsewhere,
39 you can use methods like those found on lists, dicts and sets: append,
40 extend, :meth:`~traitlets.config.LazyConfigValue.prepend` (like
41 extend, but at the front), add and update (which works both for dicts
42 and sets)::
40 To add to a collection which may have already been defined elsewhere or have
41 default values, you can use methods like those found on lists, dicts and
42 sets: append, extend, :meth:`~traitlets.config.LazyConfigValue.prepend` (like
43 extend, but at the front), add and update (which works both for dicts and
44 sets)::
43 45
44 46 c.InteractiveShellApp.extensions.append('Cython')
45 47
46 48 .. versionadded:: 2.0
47 49 list, dict and set methods for config values
48 50
49 51 Example config file
50 52 ```````````````````
51 53
52 54 ::
53 55
54 56 # sample ipython_config.py
55 c = get_config()
56 57
57 58 c.TerminalIPythonApp.display_banner = True
58 59 c.InteractiveShellApp.log_level = 20
59 60 c.InteractiveShellApp.extensions = [
60 61 'myextension'
61 62 ]
62 63 c.InteractiveShellApp.exec_lines = [
63 64 'import numpy',
64 65 'import scipy'
65 66 ]
66 67 c.InteractiveShellApp.exec_files = [
67 68 'mycode.py',
68 69 'fancy.ipy'
69 70 ]
70 71 c.InteractiveShell.colors = 'LightBG'
71 72 c.InteractiveShell.confirm_exit = False
72 73 c.InteractiveShell.editor = 'nano'
73 74 c.InteractiveShell.xmode = 'Context'
74 75
75 76 c.PrefilterManager.multi_line_specials = True
76 77
77 78 c.AliasManager.user_aliases = [
78 79 ('la', 'ls -al')
79 80 ]
80 81
82 Json Configuration files
83 ------------------------
84
85 in case where executability of configuration can be problematic, or
86 configurations need to be modified programatically, IPython also support a
87 limited set of functionalities via ``.json`` config files.
88
89 You can defined most of the configuration options via a json object which
90 hierarchy represent the value you woudl normally set on the ``c`` object of
91 ``.py`` configuration files. The following ``ipython_config.json`` file::
92
93 {
94 "InteractiveShell": {
95 "colors": "LightBG",
96 "editor": "nano"
97 },
98 "InteractiveShellApp": {
99 "extensions": [
100 "myextension"
101 ]
102 }
103 }
104
105 Is equivalent to the following ``ipython_config.py``::
106
107 c.InteractiveShellApp.extensions = [
108 'myextension'
109 ]
110
111 c.InteractiveShell.colors = 'LightBG'
112 c.InteractiveShell.editor = 'nano'
113
81 114
82 115 Command line arguments
83 116 ----------------------
84 117
85 118 Every configurable value can be set from the command line, using this
86 119 syntax::
87 120
88 121 ipython --ClassName.attribute=value
89 122
90 123 Many frequently used options have short aliases and flags, such as
91 124 ``--matplotlib`` (to integrate with a matplotlib GUI event loop) or
92 125 ``--pdb`` (automatic post-mortem debugging of exceptions).
93 126
94 127 To see all of these abbreviated options, run::
95 128
96 129 ipython --help
97 ipython notebook --help
130 jupyter notebook --help
98 131 # etc.
99 132
100 133 Options specified at the command line, in either format, override
101 134 options set in a configuration file.
102 135
103 136 The config magic
104 137 ----------------
105 138
106 139 You can also modify config from inside IPython, using a magic command::
107 140
108 141 %config IPCompleter.greedy = True
109 142
110 143 At present, this only affects the current session - changes you make to
111 144 config are not saved anywhere. Also, some options are only read when
112 145 IPython starts, so they can't be changed like this.
113 146
114 147 .. _configure_start_ipython:
115 148
116 149 Running IPython from Python
117 150 ----------------------------
118 151
119 152 If you are using :ref:`embedding` to start IPython from a normal
120 153 python file, you can set configuration options the same way as in a
121 154 config file by creating a traitlets config object and passing it to
122 155 start_ipython like in the example below.
123 156
124 157 .. literalinclude:: ../../../examples/Embedding/start_ipython_config.py
125 158 :language: python
126 159
127 160 .. _profiles:
128 161
129 162 Profiles
130 163 ========
131 164
132 165 IPython can use multiple profiles, with separate configuration and
133 166 history. By default, if you don't specify a profile, IPython always runs
134 167 in the ``default`` profile. To use a new profile::
135 168
136 169 ipython profile create foo # create the profile foo
137 170 ipython --profile=foo # start IPython using the new profile
138 171
139 172 Profiles are typically stored in :ref:`ipythondir`, but you can also keep
140 173 a profile in the current working directory, for example to distribute it
141 174 with a project. To find a profile directory on the filesystem::
142 175
143 176 ipython locate profile foo
144 177
145 178 .. _ipythondir:
146 179
147 180 The IPython directory
148 181 =====================
149 182
150 183 IPython stores its files---config, command history and extensions---in
151 184 the directory :file:`~/.ipython/` by default.
152 185
153 186 .. envvar:: IPYTHONDIR
154 187
155 188 If set, this environment variable should be the path to a directory,
156 189 which IPython will use for user data. IPython will create it if it
157 190 does not exist.
158 191
159 192 .. option:: --ipython-dir=<path>
160 193
161 194 This command line option can also be used to override the default
162 195 IPython directory.
163 196
164 197 To see where IPython is looking for the IPython directory, use the command
165 198 ``ipython locate``, or the Python function :func:`IPython.paths.get_ipython_dir`.
199
200
201 Systemwide configuration
202 ========================
203
204 It can be usefull to deploy systemwide ipython or ipykernel configuration
205 when managing environment for many users. At startup time IPython and
206 IPykernel will search for configuration file in multiple systemwide
207 locations, mainly:
208
209 - ``/etc/ipython/``
210 - ``/usr/local/etc/ipython/``
211
212 When the global install is a standalone python distribution it may also
213 search in distribution specific location, for example:
214
215 - ``$ANACONDA_LOCATION/etc/ipython/``
216
217 In those locations, Terminal IPython will look for a file called
218 ``ipython_config.py`` and ``ipython_config.json``, ipykernel will look for
219 ``ipython_kernel_config.py`` and ``ipython_kernel.json``.
220
221 Configuration files are loaded in order and merged with configuration on
222 later locatoin taking precedence on earlier locations (that is to say a user
223 can overwrite a systemwide configuration option).
224
225 You can see all locations in which IPython is looking for configuration files
226 by starting ipython in debug mode::
227
228 $ ipython --debug -c 'exit()'
229
230 Identically with ipykernel though the command is currently blocking until
231 this process is killed with ``Ctrl-\``::
232
233 $ python -m ipykernel --debug No newline at end of file
General Comments 0
You need to be logged in to leave comments. Login now