A module update in Odoo is not a file copy. It re-runs the module's data files, can alter database columns and may execute migration scripts. That is why the safe procedure always involves a backup and, ideally, a rehearsal on a copy of production.
How Odoo decides an update is available
Odoo compares the version in the module's __manifest__.py with the version recorded in the database. If the manifest number is higher, the module is flagged as upgradable.
The convention is <odoo series>.<major>.<minor>.<patch> — for example 19.0.1.0.4. The leading series matters: it tells Odoo, and the Apps Store, which Odoo version the module targets. A module whose version does not start with your series is the wrong build.
Step 1 — Back up before anything else
Take a full backup, database and filestore. A database dump without the filestore loses attachments, which is discovered at the worst possible moment.
Verify the backup can be restored. An untested backup is a hypothesis, not a safety net.
Step 2 — Rehearse on a copy
Restore the backup onto a staging instance and run the upgrade there first. This is where you find the migration that fails on your particular data — the custom field somebody added, the records in an unexpected state.
On Odoo.sh this is what staging branches are for. Self-hosted, a second container or a second database on the same server is enough.
Step 3 — Replace the files
Replace the module folder with the new version. Do not merge the two by hand: delete the old folder and put the new one in place, so that removed files actually disappear. Leftover .pyc files and deleted XML views that linger are a classic source of confusing behaviour.
Step 4 — Run the upgrade
Restart the service, then upgrade the module. From the interface: developer mode, Apps, find the module, and use the Upgrade button. From the command line, the equivalent is the -u flag with the database specified:
odoo -d my_database -u my_module --stop-after-initUse -u with a module name rather than -u all unless you have a reason. Upgrading everything touches modules that did not need it.
Step 5 — Check what the upgrade touched
Read the server log for warnings, not only errors. Then verify, in this order: the module's own menus and views load, its scheduled actions still have a sensible next execution date, its access rights and record rules are intact, and any report it prints still renders.
Scheduled actions deserve particular attention — a reloaded cron data file can reset the next run date.
What to do when an upgrade goes wrong
Restore the backup. This is the whole reason step one exists, and it is almost always faster than debugging a half-migrated database in production.
Then reproduce the failure on staging, where you can take your time, and send the log to the module author.
Next steps
Our modules follow the standard version convention, so upgrades appear in the Apps list as soon as the new build is in place. See the full range in the module catalogue.
Frequently asked questions
Does updating a module lose my data?
It should not — an upgrade re-runs data files and migrations, it does not wipe records. But because it can alter the schema, a verified backup before the upgrade is not optional.
What does the -u flag do?
odoo -d database -u module_name upgrades that module: it reloads its data files and runs its migration scripts. Adding --stop-after-init makes it exit once finished, which is what you want in a script.
Should I use -u all?
Rarely. Upgrading every module touches ones that did not need it and lengthens both the downtime and the list of things that could go wrong. Name the module you are upgrading.
Why does Odoo not show my new version?
The manifest version must be strictly higher than the one recorded in the database, and the Apps list must be refreshed. Check both, and confirm you actually replaced the files on the server the instance is running from.
Do I need to restart Odoo before upgrading?
Yes. Python code is loaded at startup, so a restart is required for the new files to be read before the upgrade runs.