You have to backup the following files:

  • .env
  • config/packages/local.yaml
  • the directory var/data/

The following stuff needs attention as well, backup if necessary:

  • all customized files
  • all added invoice templates
  • installed plugins at var/plugins/


  • All tables starting with kimai2_
  • The table migration_versions
  • Best is to backup all tables in the database with all data!

Write down the exact version of your Kimai installation:

  • bin/console kimai:version
  • git rev-parse HEAD


  • install Kimai as documented in the exact same version, which you used when you created the backup
  • make sure it works
  • restore the database backup in an empty database
  • point .env to your imported database

Now refresh your cache:

bin/console cache:clear --env=prod
bin/console cache:warmup --env=prod

FTP users: please have a look at this documentation.

At this step: test Kimai again and don’t proceed before it works as expected!

Working properly? Fine, then go ahead and restore all other files:

  • invoice templates
  • plugins
  • local.yaml

Still not satisfied and want to upgrade to the latest version?

Great! Make sure you have the migration_versions table in your database backup, before you upgrade. If not, execute bin/console doctrine:migrations:version --add --all beforehand and read the installation docs again, if you might have missed other points as well.

Now you can upgrade :-)

Pitfall version change

You restored Kimai (as documented above), but have problems when accessing it?

Maybe you have have missed an upgrade steps, which you would have done when executing a normal upgrade.

Please check the UPGRADING guide and make sure you executed all version specific tasks.


If Kimai will not load properly (e.g. you only see a white screen, maybe some pages work) the database could be the reason.

This problem can happen when you install a different (newer) version that has a different database structure then your backup.

Check your database if you have the migration_versions table. If not, go back to “Restore”.

If so: try to execute the missing database migrations with bin/console doctrine:migrations:migrate.


You see an error when executing bin/console cache:clear.

This problem can happen when a configuration change is necessary in your local.yaml. Please check the UPGRADING guide.