How To Upgrade HomeAssistant Core In A Python Venv Using uv

Home Assistant is an open source home automation platform, written in Python, which I have been running it for several years for various tasks.

I am running it using a less common method (called Home Assistant Core), which will soon not be recommended nor supported for end users. However, I have consciously decided to run it that way, rather than use a docker container, Home Assistant OS, or the other recommended versions.

These reasons for this decision include:

• Running custom shell scripts that are called by Home Assistant for notifications and such,
• Running other programs on the Raspberry Pi (e.g. RTL-SDR for weather station, MariaDB, InfluxDB and Grafana for a weather panel, ...),
• Having access to Ubuntu's vast repository of applications easily installable using apt,
• Retaining sysadmin control over the Raspberry Pi.
• Running ARM 64-bit Ubuntu's Long Term Release (LTS) versions on a Raspberry Pi 4, so as to upgrade less frequently, so less disruptions, and less maintenance.
• Running Home Assistant as a regular users, in my home directory, so there is no need to sudo (except for running systemd units).

For a few years now, I was running Home Assistant in a Python Virtual Environment (venv), as I explained in a previous post, and it was working quite well.

However, because the Home Assistant development team frequently updates to newer Python versions, and Ubuntu LTS does not have these newer versions, upgrades to Home Assistant stops working after some time.

Enter uv

Thanks to Carsten Fuchs in this post, it turns out that a company called Astral released an extremely fast tool called uv which revolutionizes how specific Python versions can be deployed in different venv instances on the same machine, isolating them from the rest of the system.

This tool will become the future method to deploy Home Assistant Core.

In the rest of this page, I detail the steps you need to install Home Assistant using uv:

Prepare For The Upgrade

HA_DIR="$HOME/ha/homeassistant"
CONF_DIR="$HOME_DIR/ha/conf"

Install uv

First you need to install the uv tool itself.
This is done using downloading a shell script and running it (scary, but ...)

cd ~
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

Install The New Python Version

Check what the latest version of Home Assistant needs for Python, then install that:

uv python install 3.13
# Verify that it is installed
uv python list

Stop Home Assistant

Assuming that you have been using a systemd unit for Home Assistant, shut down HA

sudo systemctrl stop homeassistant

Rename The Existing HA Directory

cd $HA_DIR
cd ..

mv homeassistant homeassistant-old

Create A New Venv Directory

mkdir homeassistant

Create The Venv

Now, create the new venv, with the specific Python version needed.

uv venv . --python 3.13
source ./bin/activate

Find The Latest Version of HA

# Visit here: https://github.com/home-assistant/core/releases
uv pip install homeassistant==2025.2.5

Install A Few Required Additional Components

Newer versions of Home Assistant use TurboJpeg, so we install that:

sudo apt install libturbojpeg

Instead of the default SQLite database, I use MariaDB for the recorder integration, and my connection string starts with mysql+pymysql:// ..., I need to install the following too:

uv pip install pymysql

Run A Syntax Check On HA's Config

Before starting Home Assistant, we want to check the syntax of our configuration YAML files, in case something has changed.

$HA_DIR/bin/hass -c $CONF_DIR --script check_config

If you see errors, you need to check the documentation and fix them.

Run HA Manually, And Check Its Logs

Because this is the initial run, you need to run HA manually.

$HA_DIR/bin/hass -c $CONF_DIR 

You will on the screen what Home Assistant is doing.

Because the recorder database changes regularly, Home Assistant has to do schema modification. This update does take some time to finish, depending on the size of your database.

So please be patient.

Start Home Assistant

sudo systemctrl stop homeassistant

In another terminal, run:

tail -f $CONF/home-assistant.log

Make sure there are no errors.