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

Create a database backup

Here is a one liner that creates a database backup for MySQL/MariaDB (adjust connection to your needs):

mysqldump --single-transaction -u kimai2 -p -h kimai2 > ~/kimai2-`date +%F_%H-%M`.sql

Or with SQLite

cp var/data/kimai.sqlite ~/kimai2-`date +%F_%H-%M`.sqllite


  • 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:

How to reload Kimai cache

bin/console kimai:reload --env=prod

FTP users: please have a look at this documentation.

If you are running an older version of Kimai (before 1.8) you have to use:

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

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

Working properly? If not, check your file permissions:

Fix Kimai file permission

You have to allow PHP (your webserver process) to write to var/ and it subdirectories.

Here is an example for Debian/Ubuntu (to be executed inside the Kimai directory):

chown -R :www-data .
chmod -R g+r .
chmod -R g+rw var/
chmod -R g+rw public/avatars/

Test Kimai before executing these commands (they are likely not required in a shared-hosting environment). You probably need to prefix them with sudo and the group might be called different than www-data.

Working now? 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 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 kimai:update -n.


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.