HA venv to Docker

1 minute read

Another year, another Python deprecation, another flood of posts asking how to upgrade a Python venv. 

While you can certainly do that, another option would be to move to Docker (at least assuming you’re running on Linux). Then you don’t have to do this next year. Moving to Docker is pretty simple, it’s largely a case of following the docs, and writing a compose file that points to your existing config.


  1. Install Docker CE, either from your distro’s package manager or following the official docs
  2. Write your compose file
  3. Stop your venv, and disabled the service
  4. Start your container

Install Docker

Install Docker, I personally prefer to use the official repositories, or if you’re on a Pi use the convenience script. Those are more up to date than you’ll get with your distro.

Once you’ve installed it, enable the service and start Docker - this is covered in the official docs so I won’t cover it here.

Write your compose file

For convenience, create /docker to store your compose file in - it makes it easier to find in the future.

Then, assuming your current config is in /home/homeassistant/.homeassistant you’ll use the following docker-compose.yml file:

version: '3'  
    container_name: home-assistant  
    image: homeassistant/home-assistant:stable  
      - /home/homeassistant/.homeassistant:/config  
      - TZ=Europe/London  
    restart: always  
    network_mode: host

Obviously you’ll want to update the timezone to match where you live. If you have any directly connected devices (eg USB sticks), you’ll need to map those as explained here. Once that’s done you’ll want to pull the image before continuing (the following assumes your user is in the docker group):

docker-compose pull

End the venv

Exactly how you do this will depend on your setup, but it’ll likely be something like:

sudo systemctl stop [email protected]  
sudo systemctl disable [email protected]

Start your container

In /docker, type the following:

docker-compose up -d homeassistant

You can watch the container logs with:

docker-compose logs --tail -100 -f homeassistant

That gives you the last 100 lines, and then follows the output.

Finally, see the Home Assistant docs for further information on working with HA in Docker, at least until you learn more about Docker.