# Upgrading Weblate
## Docker image upgrades
The official Weblate Docker image (see [Installing using Docker](https://docs.weblate.org/en/latest/admin/install/docker.md)) integrates all upgrade steps.
Typically, no manual interaction is needed beyond pulling the latest
(or at least newer) version.
#### SEE ALSO
[Upgrading the Docker container](https://docs.weblate.org/en/latest/admin/install/docker.md#upgrading-docker)
## Generic upgrade instructions
Always look for new changes to [Software requirements](https://docs.weblate.org/en/latest/admin/install.md#requirements) before upgrading.
Once all requirements are installed or upgraded, ensure your
`settings.py` matches the changes in the configuration (consult
`settings_example.py` for correct values).
Always check [Version-specific instructions](#version-specific-instructions) before upgrading. If you are
skipping any versions, be sure to follow instructions for all versions you are
skipping during such upgrade. It’s sometimes better to upgrade gradually to
an intermediate version to ensure a smooth migration. Upgrading across multiple
releases should work, but is not as well tested as single version upgrades!
#### NOTE
Always back up the full database before upgrading, so that you
can roll back the database if the upgrade fails, see [Backing up and moving Weblate](https://docs.weblate.org/en/latest/admin/backup.md).
1. Wait for the Celery queues to become empty, then stop the WSGI and Celery
processes to avoid old processes running while upgrading. Otherwise
incompatible changes in the database might occur.
The Celery task queue is not a stable interface across releases, so queued
tasks from the old version are not guaranteed to work after the upgrade. You
can monitor queue length in the [Management interface](https://docs.weblate.org/en/latest/admin/admin.md#management-interface) or by using
[`celery_queues`](https://docs.weblate.org/en/latest/admin/management.md#weblate-admin-celery_queues).
2. Upgrade Weblate
For pip installs it can be achieved by:
```sh
uv pip install -U "weblate[all]==version"
```
Or, if you just want to get the latest released version:
```sh
uv pip install -U "weblate[all]"
```
If you don’t want to install all of the optional dependencies do:
```sh
uv pip install -U weblate
```
Using Git checkout, you need to fetch new source code and update your installation:
```sh
cd weblate-src
git pull
# Update Weblate inside your Python environment
. ~/weblate-env/bin/uv pip install -e '.[all]'
# Install dependencies directly when not using Python environment
uv pip install --upgrade -e .
# Install optional dependencies directly when not using a Python environment
uv pip install --upgrade -e '.[all]'
```
3. New Weblate releases might have new [Python dependencies](https://docs.weblate.org/en/latest/admin/install.md#python-deps), check if they cover
the features you want.
4. Upgrade the configuration file by following either `settings_example.py`, or
[Version-specific instructions](#version-specific-instructions).
5. Upgrade the database:
```sh
weblate migrate --noinput
```
6. Collect updated static files (see [Running server](https://docs.weblate.org/en/latest/admin/install.md#server) and [Serving static files](https://docs.weblate.org/en/latest/admin/install.md#static-files)):
```sh
weblate collectstatic --noinput
```
7. If you are running an installation from Git, you should also regenerate locale
files every time you upgrade. You can do this by invoking:
```sh
weblate compilemessages
```
8. Verify that your setup is sane (see also [Production setup](https://docs.weblate.org/en/latest/admin/install.md#production)):
```sh
weblate check --deploy
```
9. Restart the Celery worker (see [Background tasks using Celery](https://docs.weblate.org/en/latest/admin/install.md#celery)).
Some upgrades run translation-memory scope backfill and consolidation in
the background using periodic Celery tasks. Keep Celery running after the
upgrade and monitor progress in Administration >
Performance report. See [Translation-memory scopes](https://docs.weblate.org/en/latest/admin/memory.md#memory-scopes) for details.
## Version-specific instructions
#### Versionchanged
Changed in version 5.0: Version specific instructions are now included in the release notes, see [Weblate 2026.11](https://docs.weblate.org/en/latest/changes.md).
### Upgrade from an older unsupported release
Direct upgrades are only supported for releases from the current or previous
calendar year. If you need to upgrade across this boundary, upgrade first to an
intermediate version as listed below. Upgrades skipping this step are not
supported and will break.
* If you are upgrading from the 2.x release, always first upgrade to 3.0.1.
* If you are upgrading from the 3.x release, always first upgrade to 4.0.4.
* If you are upgrading from the 4.x release, always first upgrade to 5.0.2.
* If you are upgrading from 5.0.x-5.9.x, always first upgrade to 5.10.4.
* Upgrades from 5.10.x and newer are currently directly supported.
#### SEE ALSO
* [Upgrade from 2.20 to 3.0 in Weblate 3.0 documentation](https://docs.weblate.org/en/weblate-3.0.1/admin/upgrade.html#upgrade-3)
* [Upgrade from 3.11 to 4.0 in Weblate 4.0 documentation](https://docs.weblate.org/en/weblate-4.0.4/admin/upgrade.html#upgrade-from-3-11-to-4-0)
* [Upgrade from 4.x to 5.0.2 in Weblate 5.0 documentation](https://docs.weblate.org/en/weblate-5.0.2/changes.html)
## Migrating from other databases to PostgreSQL
#### WARNING
MySQL and MariaDB are no longer supported in Weblate. You must migrate
to PostgreSQL before upgrading.
If you are running Weblate with MySQL or MariaDB,
consider migrating to PostgreSQL for better performance by doing the following steps.
Remember to stop both, the web and Celery servers beforehand,
otherwise you might end up with inconsistent data.
### Creating a database in PostgreSQL
It is usually a good idea to run Weblate in a separate database, and a separate user account:
```sh
# If PostgreSQL was not installed before, set the main password
sudo -u postgres psql postgres -c "\password postgres"
# Create a database user called "weblate"
sudo -u postgres createuser -D -P weblate
# Create the database "weblate" owned by "weblate"
sudo -u postgres createdb -E UTF8 -O weblate weblate
```
### Migrating to PostgreSQL using pgloader
The [pgloader](https://pgloader.io/) is a generic migration tool to migrate data to PostgreSQL.
You can use it to migrate your Weblate database.
1. Adjust your `settings.py` to use PostgreSQL as database.
2. Migrate the schema in the PostgreSQL database:
```sh
weblate migrate
weblate sqlflush | weblate dbshell
```
3. Run the pgloader to transfer the data.
The following script can be used to migrate the database, but you might
want to learn more about [pgloader](https://pgloader.io/) to better understand what it does,
and tweak it to match your setup:
> ```postgresql
> LOAD DATABASE
> FROM mysql://weblate:password@localhost/weblate
> INTO postgresql://weblate:password@localhost/weblate
> WITH include no drop, truncate, create no tables, create no indexes, no foreign keys, disable triggers, reset sequences, data only
> ALTER SCHEMA 'weblate' RENAME TO 'public'
> ;
> ```
## Migrating from Pootle
As Weblate was originally written as a replacement for Pootle, it is supported
to migrate the user accounts from it. You can dump the users from Pootle and
import them using [`importusers`](https://docs.weblate.org/en/latest/admin/management.md#weblate-admin-importusers).