Configuration

Configuration#

ITables exposes many of the datatables options. Since ITables v2.5, the default values for these options can be set in an itables.toml configuration file.

Prerequisites#

You will need ITables v2.5 or higher, and two dependencies: either tomllib or tomli, and platformdirs, which can be installed with pip install itables[config].

Configuration file#

The configuration file is identified using get_config_file from itables.config. It can be:

  • The file pointed to by the environment variable ITABLES_CONFIG, if set and non-empty (if the variable is an empty string, no configuration file is used)

  • An itables.toml file in the current directory or a parent directory

  • A tool.itables section in a pyproject.toml file in the current directory or a parent directory

Example configuration#

A simple itables.toml configuration file that makes the tables a bit more compact looks like this:

classes = ["display", "nowrap", "compact"]

If you want the Excel export button on each table, add this:

buttons = ["pageLength", "copyHtml5", "csvHtml5", "excelHtml5"]

And if you want to use the column control extension:

[[columnControl]]
target = 0
content = ["order"]
[[columnControl]]
target = "tfoot"
content = ["search"]

[ordering]
indicators = false
handler = false

Modifying the configuration#

The configuration file is loaded when itables is imported. If you make changes to the configuration file, these will take effect only when you restart Python and re-import ITables.

You can confirm which configuration file is being used (in a given directory) by running:

python -m itables.show_config
Contents