Updating FOSSBilling

Danger

Always back up first. Before any update, make full backups of your database and all FOSSBilling files. If something goes wrong, you'll need these to restore your data.

Caution

Review version-specific notes. Major releases like 0.8.0 include breaking changes to themes, templates, APIs, and configuration. Read the upgrade guide for your target version before updating, especially if you use custom themes or modules.

Automatic Updates (Recommended)

For most installations, the built-in updater is the easiest option:

1. Log in to your admin panel
2. Go to System → Update
3. Click to install the update

FOSSBilling downloads and installs the new files, enables maintenance mode, clears the cache, and logs you out. After logging back in, you will be prompted to finalize the update.

Update Finalization

Starting with 0.8.1, updates follow a two-phase process:

1. Install — New files are downloaded and deployed. Maintenance mode is enabled and you are logged out.
2. Finalize — After logging back in, FOSSBilling shows a finalization page where you apply any pending database patches. Once patches are complete, maintenance mode is restored to its previous state and you return to the dashboard.

This prevents older versions from automatically applying database patches before the new code is in place.

The updater follows the configured update branch, usually release or preview, which you can change in your configuration file.

Manual Updates

If you prefer to manage files yourself:

1. Back up your database and files
2. Download the latest release
3. Extract the files over your existing installation (overwrite existing files)
4. Delete the install folder that came with the new files
5. Log in to the admin panel and follow the finalization prompt to apply pending patches

FOSSBilling will detect the new files and direct you to the finalization page. If you navigated away, go to System → Update and use Apply Patches & Update Configuration.

If an update fails or FOSSBilling errors after updating, see Troubleshooting FOSSBilling Issues.

Version-Specific Upgrade Notes

Some releases need extra review before updating.

Upgrading from 0.7.x to 0.8.x PHP 8.3 upgrade, jQuery removal, esbuild migration, Twig filter changes, Symfony routing overhaul, theme template updates, guest API lockdown, and more.