Instructions to install Py-spy on HAOS

originally landed at How to install Py spy on a HA OS instance, please instruct - #44 by Mariusthvdb but this might be valuable to post as a standalone community guide. thanks to the relentless support by @bdraco, I can post the solution to original request for

instructions to install py-spy on HAOS (you need to run it on the host):

2 ways to install and run the required files:

1 The easiest way to run docker commands required for the py-spy is to install the ssh & web terminal add-on and disable protection mode then you can ( get into the host and) access the docker cli and follow the rest of the steps described below.

Important: this is the ssh add-on in the community add-ons repo, not the ssh add-on in the official add-ons repo. You cannot access the docker cli from the ssh add-on in the official add-ons repo.

2 On the other hand, you won’t be able to c&p commands (and results) from those terminal windows.
thats the main reason I run ssh in external terminal: to be able to c&p results

For that use the Debugging the Home Assistant Operating System | Home Assistant Developer Docs
method to create authorized keys and copy that to your instance via
ha os import on an attached usb

So you can shell into the Host, which is required for these readings.

ssh [email protected] -p 22222

After having settled the above, you can now continue with the actual setup process of the py-spy files:

docker exec -it homeassistant /bin/bash

next, download and install the correct image for py-spy for your hardware:

For the RPI4:

unzip py_spy-0.3.12-py2.py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl

For the intel based use:


There should be a py-spy binary once you call unzip in one of the directories it creates

top (to get pid for homeassistant)

go to the created dir in your /config folder using


cd scripts

Run the next commands for the actual py-spy readings to be analyzed by dev’s:

./py-spy top --pid 60

./py-spy record --pid 60 --duration 120 --rate 100

./py-spy record --pid 60 --duration 300 --rate 200

./py-spy dump --pid 60

Thanks Nick!

1 Like
bash-5.1# wget
unzip py_spy-0.3.12-py2.py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Connecting to (
Connecting to (
saving to 'py_spy-0.3.12-py2.py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl'   4% |******                                                          100% |****************************************************| 2714k  0:00:00 ETA
'py_spy-0.3.12-py2.py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl' saved
Archive:  py_spy-0.3.12-py2.py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
  inflating: py_spy-0.3.12.dist-info/METADATA
  inflating: py_spy-0.3.12.dist-info/WHEEL
  inflating: py_spy-0.3.12.dist-info/license_files/LICENSE
  inflating: py_spy-0.3.12.dist-info/RECORD
bash-5.1# cd
bash-5.1# cd scripts
bash-5.1# ./py-spy top --pid 63
thread '<unnamed>' panicked at 'called `Result::unwrap()` on an `Err` value: ParseIntError { kind: PosOverflow }', /root/.cargo/registry/src/
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
Error: receiving on a closed channel


need help