Skip to content

Update

Automatic update

An update script in your mailcow-dockerized directory will take care of updates.

Run the update script: 

./update.sh

If it needs to, it will ask you how you wish to proceed. Merge errors will be reported. Some minor conflicts will be auto-corrected (in favour for the mailcow-dockerized repository code).

Major updates

For major updates (e.g. 2026-11), update.sh shows a link to the release notes and asks before it continues. Read the release notes first, they list breaking changes and steps that may be needed. With --force, this question is skipped.

Database update after an update

On the first start after an update, php-fpm updates the database. On large installations this can take a few minutes. Dovecot, SOGo and the watchdog wait for it, their logs show Waiting for schema update....

  • Dovecot and the watchdog start anyway after 5 minutes. If the Dovecot log then shows DB schema is ..., expected ..., check the log of php-fpm (docker compose logs php-fpm-mailcow).
  • The database version is set in docker-compose.yml (DB_VERSION). If you maintain your own docker-compose.yml, keep this value from the current version.

Options

# Options can be combined

# - Check for updates and show changes
./update.sh --check

# - Do not start mailcow after applying an update
./update.sh --skip-start

# - Skip ICMP Check to public DNS resolvers (Use it only if you´ve blocked any ICMP Connections to your mailcow machine)
./update.sh --skip-ping-check

# - Switch your mailcow updates to the unstable (nightly) branch.
./update.sh --nightly

# - Switch your mailcow updates to the stable (master) branch. Default unless you changed it with --nightly.
./update.sh --stable

# - Switch your mailcow updates to the legacy branch.
./update.sh --legacy

# - Force update (unattended, but unsupported, use at own risk)
./update.sh --force

# - Run garbage collector to cleanup old image tags and exit
./update.sh --gc

# - Update with merge strategy option "ours" instead of "theirs"
#   This will **solve conflicts** when merging in favor for your local changes and should be avoided. Local changes will always be kept, unless we changed file XY, too.
./update.sh --ours

# - Don't update, but prefetch images and exit
./update.sh --prefetch

I forgot what I changed before running update.sh

See git log --pretty=oneline | grep -i "before update", you will have an output similar to this:

22cd00b5e28893ef9ddef3c2b5436453cc5223ab Before update on 2020-09-28_19_25_45
dacd4fb9b51e9e1c8a37d84485b92ffaf6c59353 Before update on 2020-08-07_13_31_31

Run git diff 22cd00b5e28893ef9ddef3c2b5436453cc5223ab to see what changed.

Can I roll back?

Only together with a backup of the database. An update can change the database (new tables and columns). An older version cannot use the newer database: its own database update fails or removes what it does not know, e.g. the data of new features.

Back up mailcow before a major update, at least the database (see Backup). To roll back, check out the commit from before the update (see above), restore the database backup and start mailcow:

docker compose down
# Replace the commit ID 22cd00b5e28893ef9ddef3c2b5436453cc5223ab with your ID
git checkout 22cd00b5e28893ef9ddef3c2b5436453cc5223ab
docker compose pull
docker compose up -d

docker-compose down
# Replace the commit ID 22cd00b5e28893ef9ddef3c2b5436453cc5223ab with your ID
git checkout 22cd00b5e28893ef9ddef3c2b5436453cc5223ab
docker-compose pull
docker-compose up -d

Hooks

You can hook into the update mechanism by adding scripts called pre_commit_hook.sh and post_commit_hook.sh to your mailcows root directory. See this for more details.

Update Cycle

  • We schedule a monthly release cycle for a major update.
  • The releases are numbered like this: YYYY-MM (e.g. 2022-05)
  • Fixes for a main Update will be stated as "Revisions" like a,b,c (e.g. 2022-05a, 2022-05b etc.)

Update variants

stable (stable updates): These updates are suitable for productive usage. They appear in a cycle of at least 1x per month.

legacy: These updates were based on the 2025-02 mailcow. Support ended in February 2026.

nightly (unstable updates): These updates are NOT suitable for production use and are for testing only. The nightly updates are ahead of the stable updates, since in these updates we test newer and more extensive features before they go live for all users.

Get Legacy Updates

Info about the Legacy Updates

Since the 2025-03 update, it is possible to obtain updates for the legacy version. This version is based on mailcow 2025-02 and will only receive security updates.

Attention

Support for the legacy version ended in February 2026

How do I get legacy updates?

To switch to the legacy updates, the update script must be executed: 

./update.sh --legacy

Get Nightly Updates

Info about the Nightly Updates

Since the 2022-08 update there is the possibility to change the update sources. Until now, the master branch on GitHub served as the only (official) update source. With the August 2022 update, however, there is now the Nightly Branch which contains unstable and major changes for testing and feedback.

The Nightly Branch always gets new updates when something is finished on the mailcow project that will be included in the new main version.

Besides the obvious changes that will be included in the next major update anyway, it also contains exclusive features that need a longer testing time.

How do I get Nightly Updates?

The process is relatively simple. With the 2022-08 update (assuming an update to the version) it is possible to run update.sh with the parameter --nightly.

Danger

Please make a backup before or follow the Best Practice Nightly Update section before switching to mailcow nightly builds. We are not responsible for any data loss/corruption, so work with caution!

The script will now change the branch with git checkout nightly, which means it will ask for the IPv6 settings again. But this is normal.

If everything worked fine (for which we made a backup before) the mailcow UI should now show the current version number and date stamp in the lower right corner:
nightly footer

Best Practice Nightly Update

Info

We recommend using the Nightly Update only if you have another machine or VM and NOT use it productively.

  1. use the cold standby script to copy the machine before the switch to the nightly builds on another system.
  2. run the update.sh script on the new machine with the parameter --nightly and confirm.
  3. experience/test the nightly updates on the secondary machine.