Debug console

The Debug console integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] adds a Python console to Home Assistant, much like the console in the developer tools of a web browser. You can run Python code inside your running Home Assistant, with full access to its live internals.

It is meant for development and for debugging problems in Home Assistant and its integrations. You do not need it for everyday use.

Prerequisites

• You need an administrator account. The debug console is not available to other users.

Configuration

To enable the debug console, add the following to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file, and restart Home Assistant afterwards:

# Example configuration.yaml entry
debug_console:

The debug console can only be enabled this way, not from the Home Assistant user interface. That way, code running in your web browser, like a custom card, cannot enable it for you.

Each administrator also sees a warning the first time they open the console. The warning explains the risks, and you can only continue after reading it for a few seconds and confirming that you understand them. Everything that runs in the console is written to the Home Assistant log, together with who ran it.

Supported functionality

Once enabled, you find the console under Settings > Tools > Debug console.

Type Python code at the prompt and press Enter to run it. The hass object is available, along with anything you assign or import.

• When your code is not complete yet, such as after for state in hass.states.async_all():, Enter starts a new line. Like the Python REPL, an empty line ends an indented block.
• Shift+Enter always starts a new line, and Ctrl+Enter (Cmd+Enter on macOS) always runs the code.
• You can use await directly, without wrapping your code in a function.
• The value of the last expression shows below your code, and is available as _ afterwards.
• Objects, lists, and dictionaries can be expanded to explore their contents. Properties show as (...) and only run when you select them, because reading them can have side effects.
• print() works like console.log in a web browser: objects you print can be expanded too.
• The console completes names, attributes, imports, and keyword arguments while you type. Inside a call, it shows the signature of the function you are calling.
• Use the arrow keys to go back through code you ran before.
• Code that waits, like await event.wait(), does not hold up the console. You can run more code meanwhile, and its result shows once it is done. While code runs, Stop stops it, and so does Ctrl+C when no text is selected.
• Pasting is blocked until you type allow pasting and press Enter, like in the console of a web browser. This protects against people who try to trick you into pasting code.

Variables and imports are kept per browser tab, also when you reload the page. Going to another page and back keeps what the console showed as well; reloading the page starts with an empty console. A session is removed 30 minutes after its browser tab disconnected, and when Home Assistant restarts.

Examples

Look at the state of an entity

hass.states.get("sun.sun")

Call an action and wait for it to finish

await hass.services.async_call(
    "homeassistant", "check_config", blocking=True
)

Known limitations

• Code runs in the event loop of Home Assistant. Blocking calls, like time.sleep() or slow file access, freeze Home Assistant until they finish, and Stop cannot stop them. Use await with asynchronous functions instead, or run blocking work with await hass.async_add_executor_job(...).

Disabling the debug console

To disable the debug console, remove debug_console: from your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file, and restart Home Assistant.

Disabling the debug console does not remove what stays behind elsewhere: the code you ran before is kept in your web browser, so you can go back to it with the arrow keys, and the Home Assistant log keeps what was logged.