Options and Settings¶
Overview¶
pandas has an options system that lets you customize some aspects of its behaviour, display-related options being those the user is most likely to adjust.
Options have a full “dotted-style”, case-insensitive name (e.g. display.max_rows
).
You can get/set options directly as attributes of the top-level options
attribute:
In [1]: import pandas as pd
In [2]: pd.options.display.max_rows
Out[2]: 15
In [3]: pd.options.display.max_rows = 999
In [4]: pd.options.display.max_rows
Out[4]: 999
The API is composed of 5 relevant functions, available directly from the pandas
namespace:
get_option()
/set_option()
- get/set the value of a single option.reset_option()
- reset one or more options to their default value.describe_option()
- print the descriptions of one or more options.option_context()
- execute a codeblock with a set of options that revert to prior settings after execution.
Note: Developers can check out pandas/core/config.py for more information.
All of the functions above accept a regexp pattern (re.search
style) as an argument,
and so passing in a substring will work - as long as it is unambiguous:
In [5]: pd.get_option("display.max_rows")
Out[5]: 999
In [6]: pd.set_option("display.max_rows",101)
In [7]: pd.get_option("display.max_rows")
Out[7]: 101
In [8]: pd.set_option("max_r",102)
In [9]: pd.get_option("display.max_rows")
Out[9]: 102
The following will not work because it matches multiple option names, e.g.
display.max_colwidth
, display.max_rows
, display.max_columns
:
In [10]: try:
....: pd.get_option("column")
....: except KeyError as e:
....: print(e)
....:
'Pattern matched multiple keys'
Note: Using this form of shorthand may cause your code to break if new options with similar names are added in future versions.
You can get a list of available options and their descriptions with describe_option
. When called
with no argument describe_option
will print out the descriptions for all available options.
Getting and Setting Options¶
As described above, get_option()
and set_option()
are available from the pandas namespace. To change an option, call
set_option('option regex', new_value)
.
In [11]: pd.get_option('mode.sim_interactive')
Out[11]: False
In [12]: pd.set_option('mode.sim_interactive', True)
In [13]: pd.get_option('mode.sim_interactive')
Out[13]: True
Note: The option ‘mode.sim_interactive’ is mostly used for debugging purposes.
All options also have a default value, and you can use reset_option
to do just that:
In [14]: pd.get_option("display.max_rows")
Out[14]: 60
In [15]: pd.set_option("display.max_rows",999)
In [16]: pd.get_option("display.max_rows")
Out[16]: 999
In [17]: pd.reset_option("display.max_rows")
In [18]: pd.get_option("display.max_rows")
Out[18]: 60
It’s also possible to reset multiple options at once (using a regex):
In [19]: pd.reset_option("^display")
option_context
context manager has been exposed through
the top-level API, allowing you to execute code with given option values. Option values
are restored automatically when you exit the with block:
In [20]: with pd.option_context("display.max_rows",10,"display.max_columns", 5):
....: print(pd.get_option("display.max_rows"))
....: print(pd.get_option("display.max_columns"))
....:
10
5
In [21]: print(pd.get_option("display.max_rows"))