Hi,
I just want to preface this, as I’ve seen a couple of queries in the comments which refers to HA in Docker Containers or HA supervised versions. TO BE VERY CLEAR FROM THE BEGINNING: This Upgrade process described here is for HomeAssistant core, running on an Ubuntu Server (specifically Ubuntu 24.04.1 LTS, but previous ones should also work), in a Python Virtual Environment.
As new versions of HA is released, sometimes (usually with Major releases), the requirements for the Python version Changes. For this reason, this process describes upgrading the Python version to the right version, and then upgrading the HomeAssistant instance.
IMPORTANT NOTE: UPGRADING PYTHON WITH REQUIREMENTS.TXT
When you upgrade Python, you have the option of using Requirements.txt to export dependencies or not.
As seen in the comments section, some people find it easier to leave it out.
Why use Requirements.txt?:
The requirements.txt file is a snapshot of all the packages and their versions installed in the current / per-upgrade Python environment. By exporting it, you create a record of the specific dependencies that are necessary for your HA Instance, or other services running on your server (if you’re using Python for more than just HA).
By using the exported requirements.txt, you ensure that the upgraded virtual environment will have the same dependencies as the old one. This helps avoid unexpected issues due to missing or mismatched packages. It does make the install more difficult as some dependencies gets deprecated between python versions, which usually require you to do some manual install / interventions to get stuff working.
For some people this matters, for some it don’t. You can do either, whichever works for you.
In summary here are the High-Level steps required for the Upgrade process.
This will be to upgrade HA to 2024.12.5 and Python to 3.13 (As per this release note: 2024.12: Scene you in 2025! 🎄 - Home Assistant)
STEPS:
- If required Upgrade Python to 3.13
- Create a backup of your old HASS environment
- Activate a new Python VE on Python 3.13
- Back Up then rebuild HASS to run in the new Python VE
- Upgrade HASS after its running from the new Python VE
- Check for other breaking changes (For example the SQL Lite version).
PROCESS:
A) Log into the shell.
B) Check / Upgrade your current python version:
python3 --version
If you have a Python version that is supported (3.13 at the time of writing this) or above then skip to step E) otherwise continue to upgrade Python as follow:
C) Download the required Python Version (HA 2024.12.x requires version 3.13):
cd /
sudo wget https://www.python.org/ftp/python/3.13.0/Python-3.13.0.tgz
Unpack it:
sudo tar --no-same-owner -xzf Python-3.13.0.tgz
Make & Install it, set it as default:
cd Python-3.13.0/
sudo apt update
sudo apt install -y build-essential zlib1g-dev libncurses5-dev libgdbm-dev libnss3-dev libssl-dev libreadline-dev libffi-dev curl libbz2-dev
sudo ./configure --enable-optimization
sudo make -j$(nproc)
sudo make altinstall
sudo update-alternatives --install /usr/bin/python3 python3 /usr/local/bin/python3.13 1
sudo update-alternatives --config python3
0
Now lets validate that Python 3.13.0 is now the default version:
python3 --version
The above should now return Python 3.13.0
Now lets do some housekeeping to ensure everything is fine before we continue:
sudo apt --fix-broken install
sudo apt install python3-minimal grub2-common
sudo python3 -m ensurepip --upgrade
sudo python3 -m pip install --upgrade pip
sudo apt update && sudo apt upgrade
sudo apt autoremove --purge
sudo apt clean
D) Freeze current Python packages
This will grab the list of current Packages used in your HASS environment, and save them to a “requirements.txt” file which you will use later on to install all the required packages in your new Python VE):
cd /home/homeassistant/.homeassistant
sudo -u homeassistant -H -s
source /srv/homeassistant/bin/activate
pip3 freeze –local > requirements-2024.12.txt
exit
E) Backup your existing HASS folder
To create a backup, we simply create a copy of the “/srv/homeassistant” folder, if you want to restore to a previous “backup”, you would copy the backup (e.g. /srv/homeassistantold) back to its original folder (/srv/homeassistant) using the cp command. Copy the folder to something like homeassistantold-todaysdate if you want to retain multiple backups of your HASS folder.
To create the backup do the following:
Stop your HASS instance:
sudo systemctl stop [email protected]
Go to the SRV folder, and copy the homeassistant program directory to your backup folder:
cd /srv
sudo mv homeassistant homeassistantold-20241226
Create a new homeassistant folder, which will run on the new version of Python:
sudo mkdir homeassistant
Set ownership of the folder for the homeassistant account:
sudo chown -R homeassistant:homeassistant homeassistant
sudo -u homeassistant -H -s
F) Create Home Assistant Python VE.
To start off, we’ll first add Python to the newly created “srv/homeassistant” directory:
cd /srv/homeassistant
python3.13 -m venv .
Then continue by setting the user on the Python folders created by the previous command:
cd /srv/homeassistant/lib
sudo -u homeassistant -H -s
Activate the Python venv:
source /srv/homeassistant/bin/activate
And now proceed to Install the requirements (noting you might have to resolve some errors, and run the last command a couple of times after editing your requirements.txt file)
cd /home/homeassistant/.homeassistant
pip3 install --upgrade pip
pip install --upgrade pip
F) Install Python Dependencies.
SKIP THIS STEP: if you have not Upgraded Python, or if you’re not using the requirements.txt file as per the IMPORTANT NOTE in the beginning of this post.
The simplest method for installing the dependencies is by running the below commands, and manually resolving any dependency errors. However, if you’re Adventurous see NOTE 2 below
cd /home/homeassistant/.homeassistant
pip3 install -r requirements-2024.12.txt
NOTE 1: If you get errors here on dependencies not being satisfied or failing, you can always go to https://pypi.org/, and look for the latest version of that dependency.
NOTE 2: I got tired of resolving dependency conflicts. So I decided instead of listing the dependencies with their versions in the requirements.txt file, That I will just allow the latest version of a dependency, for example change “acme==2.10.0” to “acme~=2.10.0” this is easily done with a find & replace in the requirements file using nano as an editor (ALT+R).
To execute this (NOTE 2) do the following:
sudo nano requirements-2024.12.txt
"ALT+R" == with >=
"CTRL X" to save and exit
Now run:
pip3 install -r requirements-2024.12.txt
This will take a lot longer, as PIP will search the latest version of each dependency.
If you still have issues, it might be permission related. This can be solved by exiting as the homeassistant user, going to the HASS directory and running pip as a SUDO user:
exit
exit
exit
cd /home/homeassistant/.homeassistant
SUDO pip3 install -r requirements-2024.12.txt
cd /srv
sudo chown -R homeassistant:homeassistant homeassistant
You would most probably find (if you attempted to remove or clean some older python libraries that some dependencies will fail, when it comes to the Installing Wheel part. If this is the case, just paste the error into chatGPT, it will tell you which dependency failed, and then do a sudo apt-get install of that element, and run the PIP installer again.
G) Upgrade HASS on the new Python version:
Now that all the requirements have been installed for Python V3.13 , you can go ahead and upgrade HASS
cd /srv/homeassistant/lib
sudo -u homeassistant -H -s
source /srv/homeassistant/bin/activate
pip3 install --upgrade hass-nabucasa
pip3 install pyOpenSSL --upgrade
pip install --use-deprecated=legacy-resolver cryptography==42.0.0
pip3 install --upgrade homeassistant
After I confirmed the downloaded version of 2024.12, you can start home assistant by running:
sudo systemctl start [email protected]
And Et Voila! HASS is Upgraded.
Once all of this is done, HASS should be the latest version, Python should be a supported version, and all should be good.
Once you have reached this point, wait for any recorder/db checks & rebuilds, and wait until HASS becomes available again, you can monitor the progress in the log file again by running:
sudo nano /home/homeassistant/.homeassistant/home-assistant.log
HOWEVER…
If you view the log and you see an Error that reads: "Version 3.22.0 of SQLite is not supported; minimum supported version is 3.31.0. " then an upgrade of SQL lite is required
To fix this, do the following:
H) Start a Fresh SSH session, & Install & configure SQL Lite by:
sudo systemctl stop [email protected]
wget https://sqlite.org/2021/sqlite-autoconf-3360000.tar.gz
tar -xvf sqlite-autoconf-3360000.tar.gz
./configure
make
sudo make install
Once the supported version of SQL lite is downloaded & installed, you will probably still have the error when trying to start Home Assistant, reason for this is because the SQL Lite install happens to the default location (/usr/local/lib/), and is not in a place where HomeAssistant expects it to be (/usr/lib/xxxx).
To correct this, you first have to determine your system type (For Example, a normal x86/x64 PC will be x86_64-linux-gnu, and a Raspberry PI it would be arm-linux-gnueabihf).
Once you know this you can copy the files from the default install to the folder HASS expects.
For a x86 or x64 Ubuntu system:
sudo cp /usr/local/lib/*sql* /usr/lib/x86_64-linux-gnu/
For a Raspberry Pi ARM system:
sudo cp /usr/local/lib/*sql* /usr/lib/arm-linux-gnueabihf/
Once copied across, we need to set the permissions on the above directories.
For a x86 or x64 Ubuntu system:
sudo chmod a+x /usr/lib/x86_64-linux-gnu/*sql*
For a Raspberry Pi ARM system:
sudo chmod a+x /usr/lib/arm-linux-gnueabihf/*sql*
Once this is done, you can Start the HASS Instance:
sudo systemctl start [email protected]
Once again, monitor the startup and you should be good to go, however recorded might take some time to rebuild the DB, depending on its size.
sudo nano /home/homeassistant/.homeassistant/home-assistant.log
Hopefully this helps, or at least gives you an understanding of the processes required to run HASS on a supported version of Python. I’ve tried to be as descriptive as possible, to convey an understanding of what is required, rather than just giving you a bunch of commands.
If you’re still having issues, reply to this thread and I’ll try to see if I can help.
