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