##// END OF EJS Templates
Describe CL precedence over config files
Thomas Kluyver -
Show More
@@ -1,152 +1,155 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 22 ``default`` profile (see :ref:`profiles`). These will typically be
23 23 located in :file:`~/.ipython/profile_default/`, and will be named
24 24 :file:`ipython_config.py`, :file:`ipython_notebook_config.py`, etc.
25 25 The settings in :file:`ipython_config.py` apply to all IPython commands.
26 26
27 27 The files typically start by getting the root config object::
28 28
29 29 c = get_config()
30 30
31 31 You can then configure class attributes like this::
32 32
33 33 c.InteractiveShell.automagic = False
34 34
35 35 Be careful with spelling--incorrect names will simply be ignored, with
36 36 no error.
37 37
38 38 To add to a collection which may have already been defined elsewhere,
39 39 you can use methods like those found on lists, dicts and sets: append,
40 40 extend, :meth:`~IPython.config.loader.LazyConfigValue.prepend` (like
41 41 extend, but at the front), add and update (which works both for dicts
42 42 and sets)::
43 43
44 44 c.InteractiveShellApp.extensions.append('rmagic')
45 45
46 46 .. versionadded:: 2.0
47 47 list, dict and set methods for config values
48 48
49 49 Example config file
50 50 ```````````````````
51 51
52 52 ::
53 53
54 54 # sample ipython_config.py
55 55 c = get_config()
56 56
57 57 c.TerminalIPythonApp.display_banner = True
58 58 c.InteractiveShellApp.log_level = 20
59 59 c.InteractiveShellApp.extensions = [
60 60 'myextension'
61 61 ]
62 62 c.InteractiveShellApp.exec_lines = [
63 63 'import numpy',
64 64 'import scipy'
65 65 ]
66 66 c.InteractiveShellApp.exec_files = [
67 67 'mycode.py',
68 68 'fancy.ipy'
69 69 ]
70 70 c.InteractiveShell.autoindent = True
71 71 c.InteractiveShell.colors = 'LightBG'
72 72 c.InteractiveShell.confirm_exit = False
73 73 c.InteractiveShell.deep_reload = True
74 74 c.InteractiveShell.editor = 'nano'
75 75 c.InteractiveShell.xmode = 'Context'
76 76
77 77 c.PromptManager.in_template = 'In [\#]: '
78 78 c.PromptManager.in2_template = ' .\D.: '
79 79 c.PromptManager.out_template = 'Out[\#]: '
80 80 c.PromptManager.justify = True
81 81
82 82 c.PrefilterManager.multi_line_specials = True
83 83
84 84 c.AliasManager.user_aliases = [
85 85 ('la', 'ls -al')
86 86 ]
87 87
88 88
89 89 Command line arguments
90 90 ----------------------
91 91
92 92 Every configurable value can be set from the command line, using this
93 93 syntax::
94 94
95 95 ipython --ClassName.attribute=value
96 96
97 97 Many frequently used options have short aliases and flags, such as
98 98 ``--matplotlib`` (to integrate with a matplotlib GUI event loop) or
99 99 ``--pdb`` (automatic post-mortem debugging of exceptions).
100 100
101 101 To see all of these abbreviated options, run::
102 102
103 103 ipython --help
104 104 ipython notebook --help
105 105 # etc.
106 106
107 Options specified at the command line, in either format, override
108 options set in a configuration file.
109
107 110 The config magic
108 111 ----------------
109 112
110 113 You can also modify config from inside IPython, using a magic command::
111 114
112 115 %config IPCompleter.greedy = True
113 116
114 117 At present, this only affects the current session - changes you make to
115 118 config are not saved anywhere.
116 119
117 120 .. _profiles:
118 121
119 122 Profiles
120 123 ========
121 124
122 125 IPython can use multiple profiles, with separate configuration and
123 126 history. By default, if you don't specify a profile, IPython always runs
124 127 in the ``default`` profile. To use a new profile::
125 128
126 129 ipython profile create foo # create the profile foo
127 130 ipython --profile=foo # start IPython using the new profile
128 131
129 132 Profiles are typically stored in :ref:`ipythondir`, but you can also keep
130 133 a profile in the current working directory, for example to distribute it
131 134 with a project. To find a profile directory on the filesystem::
132 135
133 136 ipython locate profile foo
134 137
135 138 .. _ipythondir:
136 139
137 140 The IPython directory
138 141 =====================
139 142
140 143 IPython stores its files---config, command history and extensions---in
141 144 the directory :file:`~/.ipython/` by default.
142 145
143 146 .. envvar:: IPYTHONDIR
144 147
145 148 If set, this environment variable should be the path to a directory,
146 149 which IPython will use for user data. IPython will create it if it
147 150 does not exist.
148 151
149 152 .. option:: --ipython-dir=<path>
150 153
151 154 This command line option can also be used to override the default
152 155 IPython directory.
General Comments 0
You need to be logged in to leave comments. Login now