Home Assistant can run your own Python code in four main ways. The right choice depends on how complex the code is and whether you need third-party libraries. This guide covers each option, with its limits.
Python scripts are not HA scripts
Don’t confuse the two. A Python script is a .py file that Home Assistant runs as an action. An HA script is a sequence of actions written in YAML or the UI. This guide covers Python files only.
Option 1: python_script (built in)
The python_script integration runs .py files from a folder in your configuration directory. It needs no add-on and no HACS.
-
Add this line to
configuration.yaml:python_script: -
Create a folder named
python_scriptsin your configuration directory. -
Save a file in that folder. Here is a short example,
hello.py:name = data.get("name", "world") logger.info("Hello, %s", name) hass.states.set("python_script.last_greeting", name) -
Restart Home Assistant once to load the integration. After that, run the action
python_script.reloadwhen you add or change a script, without restarting. -
Call
python_script.hellofrom an automation or from Developer tools > Actions, passingnameas data.
Every .py file becomes an action named after the file. Inside a script, read parameters with data.get("name"), and call other actions with hass.services.call(domain, service, data).
Limits
- No imports. Scripts run in a sandbox, and you cannot use
importstatements. Libraries such asrequestsare not available. - Limited objects. The sandbox provides
hass,data,logger,time,datetimeanddt_util.
Option 2: shell_command
shell_command runs a command you define in configuration.yaml. You can use it to run a Python file:
shell_command:
run_script: "python3 /config/scripts/x.py {{ arg }}"
Call it as shell_command.run_script, passing arg as data.
Keep these limits in mind:
- It runs in the Home Assistant Core container, not on your host operating system. On Home Assistant OS, any Python packages must be installed inside that container, and they can disappear after an update.
- There is a 60-second timeout. Long-running work will be cut off.
- Newer releases return the output. Recent versions return stdout, stderr and the return code as response data. The exact version varies, so check your release.
- Templated arguments can allow command injection. Never pass untrusted input into a command.
Option 3: Pyscript (from HACS)
Pyscript is a custom integration by craigbarratt, installed through HACS. It runs full Python, with imports, and it uses decorators to react to events:
- Install Pyscript from HACS, then restart Home Assistant.
- Go to Settings > Devices & services and add Pyscript.
- Turn on full import support during setup if your code needs imports.
- Put your files in the
pyscriptfolder under your configuration directory.
Pyscript provides decorators such as @state_trigger, @time_trigger and @service. These let you run a function when an entity changes, on a timer, or when Home Assistant calls it as an action.
Option 4: AppDaemon (add-on)
AppDaemon is a separate Python environment. It runs as an add-on or in its own container, and it connects to Home Assistant over its API. Apps subclass hass.Hass.
Because it runs apart from Home Assistant Core, a bug in an AppDaemon app is less likely to bring down your main system. The folder where apps live has changed between versions, so check the add-on’s documentation for your release.
Calling Home Assistant from a script on another machine
A standalone Python script on another computer can control Home Assistant through its REST API. Send HTTP requests with the requests library, and authenticate with a long-lived access token from your Home Assistant profile.
Which one should you use?
- Small helpers with no imports:
python_script. - Running an external command:
shell_command, with the limits above. - Automations that need libraries: Pyscript from HACS.
- Heavier, separate workloads: AppDaemon.
- A new device or service integration: a custom integration, which lives under
custom_components. Our HACS guide explains how custom integrations arrive through HACS.
Safety
Only pass trusted values into shell_command. A value that contains shell characters can run commands you didn’t intend.