Pandas describe_option(): Inspect Settings and Defaults

Inspect registered Pandas option descriptions, distinguish default and current values and generate the installed option catalogue.

Show Table of Contents ↓

Describe a specific option 🔝

describe_option() prints an option description with its registered default and current value. The original max_rows example is retained using the full name. Text and defaults may differ by installed Pandas version.

import pandas as pd
pd.describe_option("display.max_rows")
assert isinstance(pd.get_option("display.max_rows"), (int, type(None)))

Expected output

display.max_rows : int
    If max_rows is exceeded, switch to truncate view. Depending on
    `large_repr`, objects are either centrally truncated or printed as
    a summary view.

    'None' value means unlimited. Beware that printing a large number of rows
    could cause your rendering environment (the browser, etc.) to crash.

    In case python/IPython is running in a terminal and `large_repr`
    equals 'truncate' this can be set to 0 and pandas will auto-detect
    the height of the terminal and print a truncated object which fits
    the screen height. The IPython notebook, IPython qtconsole, or
    IDLE do not run in a terminal and hence it is not possible to do
    correct auto-detection.
    [default: 60] [currently: 60]

Inspect a temporary custom value 🔝

The original value of 10 is retained. Default and current value are different concepts. Use a context so this demonstration leaves your earlier settings intact.

before = pd.get_option("display.max_rows")
with pd.option_context("display.max_rows", 10):
    pd.describe_option("display.max_rows")
    assert pd.get_option("display.max_rows") == 10
print("Previous value restored:", pd.get_option("display.max_rows") == before)
assert pd.get_option("display.max_rows") == before

Expected output

display.max_rows : int
    If max_rows is exceeded, switch to truncate view. Depending on
    `large_repr`, objects are either centrally truncated or printed as
    a summary view.

    'None' value means unlimited. Beware that printing a large number of rows
    could cause your rendering environment (the browser, etc.) to crash.

    In case python/IPython is running in a terminal and `large_repr`
    equals 'truncate' this can be set to 0 and pandas will auto-detect
    the height of the terminal and print a truncated object which fits
    the screen height. The IPython notebook, IPython qtconsole, or
    IDLE do not run in a terminal and hence it is not possible to do
    correct auto-detection.
    [default: 60] [currently: 10]
Previous value restored: True

Describe a selected group of options 🔝

describe_option accepts a pattern and prints all matching descriptions. Restrict it to known names rather than relying on a vague partial match.

pd.describe_option(r"^display\.max_(rows|columns)$")

Expected output

display.max_columns : int
    If max_cols is exceeded, switch to truncate view. Depending on
    `large_repr`, objects are either centrally truncated or printed as
    a summary view.

    'None' value means unlimited. Beware that printing a large number of
    columns could cause your rendering environment (the browser, etc.) to
    crash.

    In case python/IPython is running in a terminal and `large_repr`
    equals 'truncate' this can be set to 0 or None and pandas will auto-detect
    the width of the terminal and print a truncated object which fits
    the screen width. The IPython notebook, IPython qtconsole, or IDLE
    do not run in a terminal and hence it is not possible to do
    correct auto-detection and defaults to 20.
    [default: 0] [currently: 0]
display.max_rows : int
    If max_rows is exceeded, switch to truncate view. Depending on
    `large_repr`, objects are either centrally truncated or printed as
    a summary view.

    'None' value means unlimited. Beware that printing a large number of rows
    could cause your rendering environment (the browser, etc.) to crash.

    In case python/IPython is running in a terminal and `large_repr`
    equals 'truncate' this can be set to 0 and pandas will auto-detect
    the height of the terminal and print a truncated object which fits
    the screen height. The IPython notebook, IPython qtconsole, or
    IDLE do not run in a terminal and hence it is not possible to do
    correct auto-detection.
    [default: 60] [currently: 60]

Get the installed option catalogue 🔝

The original long catalogue includes settings from an older Pandas release, including removed names. Generate the list from the installed version instead of treating that snapshot as current. Call pd.describe_option() directly to print the full list. This example captures that same output and prints selected catalogue counts so the notebook stays readable.

import io
from contextlib import redirect_stdout
buffer = io.StringIO()
with redirect_stdout(buffer):
    pd.describe_option()
catalogue = buffer.getvalue()
headers = [line.split(" :", 1)[0] for line in catalogue.splitlines()
           if line and not line[0].isspace() and " :" in line]
for prefix in ["display.", "compute.", "io.", "mode.", "plotting."]:
    print(prefix, sum(name.startswith(prefix) for name in headers))
assert "display.max_rows" in catalogue and "display.max_columns" in catalogue

Expected output

display. 29
compute. 3
io. 12
mode. 5
plotting. 2

Understand the option groups 🔝

Group	Purpose
display	Text/HTML rendering, rows, columns, width, precision and related presentation.
compute	Computation-related settings; available acceleration depends on installed libraries.
io	File reader/writer configuration and engines.
mode	Behaviour settings; some historical options are deprecated or removed.
plotting	Plot backends and related configuration.

The no-argument catalogue includes all registered options, not just display options. Describing an option does not install its optional dependency or change its value. Do not copy removed historical option names such as display.column_space or mode.use_inf_as_null into current code.

Inspect a setting before changing it 🔝

Use descriptions to understand a setting, get_option to read it and option_context for a temporary rendering decision. No table values change.

pd.describe_option("display.precision")
data = pd.DataFrame({"amount": [1.23456, 9.87654]})
with pd.option_context("display.precision", 2):
    print(data)
assert data["amount"].tolist() == [1.23456, 9.87654]

Expected output

display.precision : int
    Floating point output precision in terms of number of places after the
    decimal, for regular formatting as well as scientific notation. Similar
    to ``precision`` in :meth:`numpy.set_printoptions`.
    [default: 6] [currently: 6]
   amount
0    1.23
1    9.88

Common mistakes 🔝

describe_option() prints text and normally returns None; it does not return an option-value mapping. Use get_option() for values. Default values are not necessarily your previous values. Prefer option_context() for temporary changes and reset_option() for defaults. Option names and documentation can change between versions, so regenerate the catalogue after upgrading.

Exercise: inspect and temporarily set precision 🔝

Describe display.precision, temporarily set it to three, verify its value, then verify the original value was restored.

Exercise solution 🔝

Read the existing value first and keep the change scoped.

saved = pd.get_option("display.precision")
pd.describe_option("display.precision")
with pd.option_context("display.precision", 3):
    print("Inside:", pd.get_option("display.precision"))
    assert pd.get_option("display.precision") == 3
print("Restored:", pd.get_option("display.precision") == saved)
assert pd.get_option("display.precision") == saved

Expected output

display.precision : int
    Floating point output precision in terms of number of places after the
    decimal, for regular formatting as well as scientific notation. Similar
    to ``precision`` in :meth:`numpy.set_printoptions`.
    [default: 6] [currently: 6]
Inside: 3
Restored: True

Practice in Google Colab 🔝

Open in Google Colab View on GitHub

Run examples in order, inspect the table display and try the exercise. Save a copy to keep edits.

Reference: Pandas describe_option() documentation.

Subhendu Mohapatra

Author & Instructor at plus2net

I write and maintain practical tutorials on Python, PHP, SQL, JavaScript, HTML, jQuery, and web development at plus2net. The tutorials focus on clear explanations, working examples, and code that readers can test and adapt while learning.

About the author Watch on YouTube

Connect:

Subscribe to our YouTube Channel here