.. _options:
{{ header }}
********************
Options and settings
********************
Overview
--------
pandas has an options API configure and customize global behavior related to
:class:`DataFrame` display, data behavior and more.
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:
.. ipython:: python
import pandas as pd
pd.options.display.max_rows
pd.options.display.max_rows = 999
pd.options.display.max_rows
The API is composed of 5 relevant functions, available directly from the ``pandas``
namespace:
* :func:`~pandas.get_option` / :func:`~pandas.set_option` - get/set the value of a single option.
* :func:`~pandas.reset_option` - reset one or more options to their default value.
* :func:`~pandas.describe_option` - print the descriptions of one or more options.
* :func:`~pandas.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_init.py <https://github.com/pandas-dev/pandas/blob/main/pandas/core/config_init.py>`_ for more information.
All of the functions above accept a regexp pattern (``re.search`` style) as an argument,
to match an unambiguous substring:
.. ipython:: python
pd.get_option("display.chop_threshold")
pd.set_option("display.chop_threshold", 2)
pd.get_option("display.chop_threshold")
pd.set_option("chop", 4)
pd.get_option("display.chop_threshold")
The following will **not work** because it matches multiple option names, e.g.
``display.max_colwidth``, ``display.max_rows``, ``display.max_columns``:
.. ipython:: python
:okexcept:
pd.get_option("max")
.. warning::
Using this form of shorthand may cause your code to break if new options with similar names are added in future versions.
.. ipython:: python
:suppress:
:okwarning:
pd.reset_option("all")
.. _options.available:
Available options
-----------------
You can get a list of available options and their descriptions with :func:`~pandas.describe_option`. When called
with no argument :func:`~pandas.describe_option` will print out the descriptions for all available options.
.. ipython:: python
pd.describe_option()
Getting and setting options
---------------------------
As described above, :func:`~pandas.get_option` and :func:`~pandas.set_option`
are available from the pandas namespace. To change an option, call
``set_option('option regex', new_value)``.
.. ipython:: python
pd.get_option("mode.sim_interactive")
pd.set_option("mode.sim_interactive", True)
pd.get_option("mode.sim_interactive")
.. note::
The option ``'mode.sim_interactive'`` is mostly used for debugging purposes.
You can use :func:`~pandas.reset_option` to revert to a setting's default value
.. ipython:: python
:suppress:
pd.reset_option("display.max_rows")
.. ipython:: python
pd.get_option("display.max_rows")
pd.set_option("display.max_rows", 999)
pd.get_option("display.max_rows")
pd.reset_option("display.max_rows")
pd.get_option("display.max_rows")
It's also possible to reset multiple options at once (using a regex):
.. ipython:: python
:okwarning:
pd.reset_option("^display")
:func:`~pandas.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:
.. ipython:: python
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"))
print(pd.get_option("display.max_rows"))
print(pd.get_option("display.max_columns"))
Setting startup options in Python/IPython environment
-----------------------------------------------------
Using startup scripts for the Python/IPython environment to import pandas and set options makes working with pandas more efficient.
To do this, create a ``.py`` or ``.ipy`` script in the startup directory of the desired profile.
An example where the startup folder is in a default IPython profile can be found at:
.. code-block:: none
$IPYTHONDIR/profile_default/startup
More information can be found in the `IPython documentation
<https://ipython.org/ipython-doc/stable/interactive/tutorial.html#startup-files>`__. An example startup script for pandas is displayed below:
.. code-block:: python
import pandas as pd
pd.set_option("display.max_rows", 999)
pd.set_option("display.precision", 5)
.. _options.frequently_used:
Frequently used options
-----------------------
The following is a demonstrates the more frequently used display options.
``display.max_rows`` and ``display.max_columns`` sets the maximum number
of rows and columns displayed when a frame is pretty-printed. Truncated
lines are replaced by an ellipsis.
.. ipython:: python
df = pd.DataFrame(np.random.randn(7, 2))
pd.set_option("display.max_rows", 7)
df
pd.set_option("display.max_rows", 5)
df
pd.reset_option("display.max_rows")
Once the ``display.max_rows`` is exceeded, the ``display.min_rows`` options
determines how many rows are shown in the truncated repr.
.. ipython:: python
pd.set_option("display.max_rows", 8)
pd.set_option("display.min_rows", 4)
# below max_rows -> all rows shown
df = pd.DataFrame(np.random.randn(7, 2))
df
# above max_rows -> only min_rows (4) rows shown
df = pd.DataFrame(np.random.randn(9, 2))
df
pd.reset_option("display.max_rows")
pd.reset_option("display.min_rows")
``display.expand_frame_repr`` allows for the representation of a
:class:`DataFrame` to stretch across pages, wrapped over the all the columns.
.. ipython:: python
df = pd.DataFrame(np.random.randn(5, 10))
pd.set_option("expand_frame_repr", True)
df
pd.set_option("expand_frame_repr", False)
df
pd.reset_option("expand_frame_repr")
``display.large_repr`` displays a :class:`DataFrame` that exceed
``max_columns`` or ``max_rows`` as a truncated frame or summary.
.. ipython:: python
df = pd.DataFrame(np.random.randn(10, 10))
pd.set_option("display.max_rows", 5)
pd.set_option("large_repr", "truncate")
df
pd.set_option("large_repr", "info")
df
pd.reset_option("large_repr")
pd.reset_option("display.max_rows")
``display.max_colwidth`` sets the maximum width of columns. Cells
of this length or longer will be truncated with an ellipsis.
.. ipython:: python
df = pd.DataFrame(
np.array(
[
["foo", "bar", "bim", "uncomfortably long string"],
["horse", "cow", "banana", "apple"],
]
)
)
pd.set_option("max_colwidth", 40)
df
pd.set_option("max_colwidth", 6)
df
pd.reset_option("max_colwidth")
``display.max_info_columns`` sets a threshold for the number of columns
displayed when calling :meth:`~pandas.DataFrame.info`.
.. ipython:: python
df = pd.DataFrame(np.random.randn(10, 10))
pd.set_option("max_info_columns", 11)
df.info()
pd.set_option("max_info_columns", 5)
df.info()
pd.reset_option("max_info_columns")
``display.max_info_rows``: :meth:`~pandas.DataFrame.info` will usually show null-counts for each column.
For a large :class:`DataFrame`, this can be quite slow. ``max_info_rows`` and ``max_info_cols``
limit this null check to the specified rows and columns respectively. The :meth:`~pandas.DataFrame.info`
keyword argument ``show_counts=True`` will override this.
.. ipython:: python
df = pd.DataFrame(np.random.choice([0, 1, np.nan], size=(10, 10)))
df
pd.set_option("max_info_rows", 11)
df.info()
pd.set_option("max_info_rows", 5)
df.info()
pd.reset_option("max_info_rows")
``display.precision`` sets the output display precision in terms of decimal places.
.. ipython:: python
df = pd.DataFrame(np.random.randn(5, 5))
pd.set_option("display.precision", 7)
df
pd.set_option("display.precision", 4)
df
``display.chop_threshold`` sets the rounding threshold to zero when displaying a
:class:`Series` or :class:`DataFrame`. This setting does not change the
precision at which the number is stored.
.. ipython:: python
df = pd.DataFrame(np.random.randn(6, 6))
pd.set_option("chop_threshold", 0)
df
pd.set_option("chop_threshold", 0.5)
df
pd.reset_option("chop_threshold")
``display.colheader_justify`` controls the justification of the headers.
The options are ``'right'``, and ``'left'``.
.. ipython:: python
df = pd.DataFrame(
np.array([np.random.randn(6), np.random.randint(1, 9, 6) * 0.1, np.zeros(6)]).T,
columns=["A", "B", "C"],
dtype="float",
)
pd.set_option("colheader_justify", "right")
df
pd.set_option("colheader_justify", "left")
df
pd.reset_option("colheader_justify")
.. _basics.console_output:
Number formatting
------------------
pandas also allows you to set how numbers are displayed in the console.
This option is not set through the ``set_options`` API.
Use the ``set_eng_float_format`` function
to alter the floating-point formatting of pandas objects to produce a particular
format.
.. ipython:: python
import numpy as np
pd.set_eng_float_format(accuracy=3, use_eng_prefix=True)
s = pd.Series(np.random.randn(5), index=["a", "b", "c", "d", "e"])
s / 1.0e3
s / 1.0e6
.. ipython:: python
:suppress:
:okwarning:
pd.reset_option("^display")
Use :meth:`~pandas.DataFrame.round` to specifically control rounding of an individual :class:`DataFrame`
.. _options.east_asian_width:
Unicode formatting
------------------
.. warning::
Enabling this option will affect the performance for printing of DataFrame and Series (about 2 times slower).
Use only when it is actually required.
Some East Asian countries use Unicode characters whose width corresponds to two Latin characters.
If a DataFrame or Series contains these characters, the default output mode may not align them properly.
.. ipython:: python
df = pd.DataFrame({"国ç±": ["UK", "日本"], "åå‰": ["Alice", "ã—ã®ã¶"]})
df
Enabling ``display.unicode.east_asian_width`` allows pandas to check each character's "East Asian Width" property.
These characters can be aligned properly by setting this option to ``True``. However, this will result in longer render
times than the standard ``len`` function.
.. ipython:: python
pd.set_option("display.unicode.east_asian_width", True)
df
In addition, Unicode characters whose width is "ambiguous" can either be 1 or 2 characters wide depending on the
terminal setting or encoding. The option ``display.unicode.ambiguous_as_wide`` can be used to handle the ambiguity.
By default, an "ambiguous" character's width, such as "¡" (inverted exclamation) in the example below, is taken to be 1.
.. ipython:: python
df = pd.DataFrame({"a": ["xxx", "¡¡"], "b": ["yyy", "¡¡"]})
df
Enabling ``display.unicode.ambiguous_as_wide`` makes pandas interpret these characters' widths to be 2.
(Note that this option will only be effective when ``display.unicode.east_asian_width`` is enabled.)
However, setting this option incorrectly for your terminal will cause these characters to be aligned incorrectly:
.. ipython:: python
pd.set_option("display.unicode.ambiguous_as_wide", True)
df
.. ipython:: python
:suppress:
pd.set_option("display.unicode.east_asian_width", False)
pd.set_option("display.unicode.ambiguous_as_wide", False)
.. _options.table_schema:
Table schema display
--------------------
:class:`DataFrame` and :class:`Series` will publish a Table Schema representation
by default. This can be enabled globally with the
``display.html.table_schema`` option:
.. ipython:: python
pd.set_option("display.html.table_schema", True)
Only ``'display.max_rows'`` are serialized and published.
.. ipython:: python
:suppress:
pd.reset_option("display.html.table_schema")