How to migrate from Toggl Track to Kimai
Move Toggl Track to self-hosted Kimai: export entries as CSV, set time zones, currency and rates first, import with the free Importer plugin, reconcile totals.
In short
- Kimai’s free Importer plugin reads the CSV export of Toggl Track’s Detailed report, which needs a paid Toggl plan: the Free plan exports reports as PDF only.
- Each imported entry keeps its client, project, task, tags, billable flag and amount; Toggl rates, estimates, fixed fees, invoices and approvals are set up again in Kimai.
- Kimai reads an imported entry’s times in its user’s time zone, so each account gets the time zone of the person’s Toggl reports before the first file goes in.
- The switch waits until Kimai’s totals per customer and month match Toggl’s, in hours and in amounts, for every month brought across.
On this page (10)
Moving from Toggl Track to Kimai is an import with a setup around it. Kimai’s free Importer plugin reads the CSV export of Toggl’s Detailed report, so every time entry arrives with its client, project, task, tags, billable flag and amount. What the file leaves out, the rates, budgets, invoices and approvals, is set up again in Kimai, and part of the setup has to exist before the first file goes in, because the importer creates whatever it does not find, with the defaults it finds. The move is finished when Kimai’s totals match Toggl’s for every month you brought across. This guide covers the order we run it in, and the places it usually goes wrong.
Why teams move from Toggl Track to Kimai
Three reasons come up again and again.
- Timesheets in your own database. Entries say who worked for which client, on what and when, and their descriptions often name matters and people. With Kimai on your own machines, they sit in a MariaDB database in the location you choose.
- No plan tiers for the core. In Toggl Track, billable rates and tasks come with the Starter plan, timesheet approvals with Premium, and single sign-on with Premium or Enterprise. Kimai has no per-user fee, and SAML and LDAP sign-in, rates, invoicing and the API are in its open-source core.
- Invoices from the same records. Kimai turns entries into invoices from templates you control, numbered in your own sequence, and marks the entries it invoiced so regular users cannot change them afterwards. Toggl’s invoices use a fixed layout, and Toggl has no built-in way to mark the entries on an invoice as paid.
What you give up is real. Toggl’s browser extension starts a timer inside many web tools, and Toggl publishes its own desktop and mobile apps. Kimai is a web app that people can add to their home screen, and the mobile and desktop clients listed on its integrations page come from other developers, some free and some paid. Saved and scheduled reports are rebuilt from Kimai’s reports and exports, and someone has to run the service, which is the part Pilae takes on.
Step 1: take the exports while the subscription is active
Everything that follows works from these files, so take them first, from a workspace admin account.
- Time entries, as CSV. Open Reports, then Detailed, choose a date range, and click Export for a CSV file. Toggl documents this in its article on exporting data. CSV and Excel exports are a paid plan feature, and only admins export every member’s entries: a regular user gets their own, plus those of projects they manage. If you work in several workspaces, switch to each one and export it separately.
- Formats first. Kimai’s documentation warns that a wrong date format in Toggl ends in parse errors. Before exporting, set the time format to 24-hour and the date format to year, month, day in Toggl’s Profile settings, so dates read like
2024-04-20and times like16:30:00, and pick a duration format in hours, minutes and seconds, as in Kimai’s example04:30:00. Turn rounding off in the report, so durations are the ones people recorded. - Every column the importer reads. Kimai’s documentation lists all of these as mandatory for its Toggl format:
User,Email,Client,Project,Task,Description,Billable,Start date,Start time,End date,End time,Duration,TagsandAmount, whose header carries the currency. Open the first export and check its header row against this list; if a column is missing, add it to the report table through the + icon and export again. - One file per period. The importer screen shows its limits on file size and rows per file. Export one month or one quarter per file, so each file stays inside them and covers a range of its own.
- The structure and the record. Admins can export workspace data under Settings, Data Export: projects, clients and the rest as JSON, and invoices as PDF. Keep it as the record of what Toggl held. For the rebuild in step 4, Toggl’s API returns the same structure in a usable form:
GET /api/v9/workspaces/{workspace_id}/projectsgives each project’s client, rate, currency, estimated hours, fixed fee and dates, and/clients,/usersand/rates/{level}/{level_id}give the rest.
Take all of it before the plan changes: CSV export needs the paid plan, and Toggl hides the task names on entries once a subscription is cancelled. This guide covers Toggl Track; Toggl’s other products have their own exports and API.
Step 2: set up Kimai before the first file
The importer creates customers, projects, activities, tags and users it does not find, so what they are created with is decided now.
- Install the Importer plugin. It is listed as free in the Kimai store, from Kimai’s author. Unpack it into
var/plugins/ImportBundle/, then rebuild the cache withbin/console kimai:reload --env=prod. It appears under System, Importer, for users with theimporterpermission, which Kimai gives to super administrators by default. - Time zones. Kimai reads the times in an imported row in the time zone of the user the entry belongs to, and gives the users it creates the default time zone from System, Settings. Toggl, for its part, shows each person’s entries in reports in that person’s own Reports Timezone, from their account settings. Set Kimai’s default to the time zone most of the team uses, and, as Kimai’s documentation asks, create an account by hand with the right time zone for everyone whose Toggl Reports Timezone differs.
- Currency. The importer does not bring currencies: the currency in the
Amountheader is not stored. Set the default currency for new customers under System, Settings before the import, then check each customer afterwards. A customer’s currency is the one its entries are shown in and its invoices are printed in. - Email addresses. The importer finds people by email first, then by the
Usercolumn. If anyone tracked time in Toggl under a personal address, replace it in the files with the address your identity provider will send at sign-in, so history and sign-in meet on one account. - Rules that refuse entries stay off. Kimai validates each imported entry like one typed in by hand. A project’s Times locked until date, project start and end dates, budgets with overbooking forbidden and a ban on overlapping entries can each refuse an imported entry. Leave them off, and switch them on in step 7.
| Toggl Track | Kimai |
|---|---|
| Workspace | One Kimai installation |
| Client | Customer |
| Project | Project, under its customer |
| Task | Activity |
| Tags | Tags |
| Billable flag | Billable flag; only billable entries are invoiced |
| Amount on an entry | The entry’s price, stored with it |
| Member | User, matched by email |
| Private project and its team | Project with a team assigned |
| Project estimate | Time budget, lifetime or monthly |
| Fixed fee | Money budget, plus an entry with a fixed price to invoice |
| Invoices | Invoices from templates, with an export flag on the entries |
| Timesheet approvals (Premium) | An approval plugin from the Kimai store |
| Browser extension, mobile apps | The web app, or a client listed on Kimai’s integrations page |
Step 3: import into a scratch instance and read the result
Build a scratch Kimai the way production will be built, with the same plugins, and import the files there first, oldest period first. Kimai’s importer documentation lists the columns of each format.
What the Toggl import brings across
Imported
- Every entry with its start, end and duration
- Description, tags and billable flag
- The entry’s amount, as its stored price
- Customers, projects and activities, created from the names in the file
- Users, matched by email or created
Set up again
- Billable rates at every level, and labour costs
- Project estimates, fixed fees and recurring budgets
- Teams and who sees which project
- Invoices, their numbering and their history
- Approvals, saved reports and integrations
Then read what arrived.
- Errors. The importer shows errors on the fields they concern. A message that a time string could not be parsed means the date or time format of the export, so fix it in Toggl’s profile and export again.
- Names. Customers, projects and activities are created from the names in the file, so two spellings of one client become two customers. Fix the names in Toggl or in the files, and import again into a fresh scratch instance.
- Entries without a task. Toggl leaves the
Taskcolumn empty when no task was used, and every Kimai entry has an activity. Look at what those entries became, and fill the column in the files if you want them under a named activity. - People. Each user exists once, with the right email and time zone. Open a handful of entries per person and compare their start and end with Toggl, especially around midnight and month ends, where a wrong time zone moves an entry to another day or month.
Give each file a date range of its own, and import each one once. To redo a period, delete what it created or rebuild the scratch instance, rather than importing the same file twice.
Step 4: rebuild rates, budgets and teams
Rates. Toggl applies the most granular of five rates: workspace, workspace member, project, project member and task. Kimai has rates on customers, projects and activities, each with an optional rule per user, and falls back to the hourly rate in each user’s preferences. An activity rate beats a project rate, which beats a customer rate, and at the same level a rule for a specific user beats the general one.
| Toggl rate | Kimai |
|---|---|
| Workspace rate | Each user’s hourly rate, the fallback for every entry |
| Workspace member | That user’s hourly rate |
| Project rate | Project rate |
| Project member rate | Project rate for that user |
| Task rate | Activity rate |
| Labour cost | Internal rate |
Kimai adds what Toggl does not have, such as one rate per customer. Kimai stores each entry’s price with the entry and applies a rate change to new entries only. An imported entry, though, carries Toggl’s amount without the hourly or fixed rate behind it, so saving it again for any reason, from its edit form or a batch update, recalculates its price from the rates set up in Kimai. Leave imported history unedited.
Budgets. Toggl’s project estimates and fixed fees are not in the time entry file. Kimai has time and money budgets on customers, projects and activities, counted either over all time or per month, which covers projects that recur monthly in Toggl. The same Importer plugin reads a project CSV with Budget, TimeBudget and BudgetType columns, so a file built from the project list of step 1 sets them in one pass. Set them after the history is in: a lifetime budget counts every billable entry ever recorded, and with overbooking forbidden, Kimai refuses entries beyond it. A budget never changes an invoice, so a fixed fee is billed through an entry with a fixed price.
Teams. A Toggl private project is visible to its members. In Kimai, a project or customer with a team assigned is visible only to that team, and team leads see their team’s timesheets. Recreate the teams, then assign them.
Step 5: reconcile totals per customer and month
This is the step that decides the date of the switch. For every month you imported, compare the same figures on both sides.
- In Toggl, the Summary report for one calendar month, grouped by client and then project, with rounding off, gives total hours, billable hours and revenue in each currency.
- In Kimai, the Monthly report under Reporting gives hours and revenue per project for a month, which add up per customer.
Write the figures into one table per customer and month, and chase every difference before moving on. The usual causes are an account with the wrong time zone, which moves entries across a month end, a date read with day and month swapped, rounding on one side only, a person matched to the wrong account, and a client spelt two ways. The finished table is your record that the history arrived whole.
Then mark what was already billed. Kimai uses an export flag for entries that have gone onto an invoice or an export: flagged entries are left out of new invoices by default, and regular users can no longer change them. Toggl has no invoiced state of its own, though its documentation suggests tagging billed entries, and tags come across. Set the flag from the export screen, not with a batch update, which would recalculate the imported prices: under Time Tracking, Export, filter on the months or the tag that were invoiced from Toggl and create an export with Mark as exported on.
Step 6: connect sign-in, invoices and approvals
Sign-in. Kimai signs people in through SAML or LDAP, both in the core, and has no OpenID Connect sign-in. With SAML, through Keycloak or Microsoft Entra ID, configured in Kimai’s local.yaml, Kimai matches the SAML NameID, or an attribute you name, against usernames and email addresses. So the provider sends the email address people used in Toggl, and they land on the account that holds their history. Directory groups map to Kimai roles at each sign-in, and a local account that signs in through SAML once stays a SAML account. With LDAP, try a first sign-in on the scratch instance and check that it lands on the imported account rather than creating a second one.
Invoices. Each invoice template names your own company as issuer, set up as a customer with its address and VAT number, plus the tax rate and payment terms. Templates can be uploaded as DOCX, ODS or XLSX, and the Kimai community shares templates in a public repository. Invoices take one customer at a time, in that customer’s currency, and include billable entries only. To continue your existing numbering, Kimai’s invoice number format accepts an offset on its counters, so the first invoice from Kimai follows the last one from Toggl. Toggl does not keep the invoices it generates, so past invoices stay as the PDFs downloaded when they were made, and Kimai’s invoice history starts empty. For e-invoicing, Kimai points to its Invoice+ plugin, which is paid for self-hosted installations; the store also lists a free third-party plugin for Swiss QR-bills.
Approvals. Kimai’s core has a lockdown period, which stops people changing entries of a closed month after a grace period. Approval workflows come from plugins: the Approval workflow for timesheets, a free third-party plugin, approves week by week, and Kimai’s working hours, vacation, sickness and public holidays plugin, which is paid, adds monthly approvals.
Step 7: cut over at a month end
The cutover, in order
- History: Every month up to the last closed one is imported and reconciled in production, as in the scratch instance.
- Switch: At the month end, people stop recording in Toggl and start in Kimai the next morning.
- Final file: The month that just ended goes in as one more file, with its own date range, and is reconciled like the others.
- Lock: The lockdown period, project locks, budgets and the rules left off in step 2 are switched on.
- Close: Toggl stays readable until the first invoicing run from Kimai is done, then a final export is kept and the subscription ends.
Brief people before the first day: the Kimai address, how they sign in, and how to add Kimai to their phone’s home screen. Keep Toggl’s last CSV and data export with the reconciliation table.
Running Kimai in production
A Kimai instance is small, but it holds the records your invoices come from.
- MariaDB or MySQL. Kimai supports those two only; PostgreSQL is not supported.
- Three directories on volumes.
var/dataholds generated invoices,var/invoicesuploaded invoice templates andvar/pluginsthe plugin code. A template kept only inside the container is lost when the container is replaced. - Backups taken together. The database and the three directories are copied at the same moment, and a restore goes onto the Kimai version the copy was taken on.
- Upgrades with plugins in mind. The container migrates the database when it starts, so the way back is the copy taken just before. Each plugin release names the minimum Kimai version it needs, so plugins are checked against every Kimai release.
Pilae operates Kimai this way: on its own MariaDB, with the three directories on volumes from the first day, daily encrypted backups stored offsite in the country your contract names, and on Enterprise a restore test every month recorded in the console. Sign-on goes through SAML to Keycloak or your existing identity provider, with directory groups mapped to Kimai roles. Every installed plugin is checked against a release before the Pilae Agent rehearses the upgrade on a copy, waits for your approval and applies it in your window. It runs on your premises or on dedicated machines in Pilae Cloud, answering only on your private network.
Let Pilae run the move
Pilae runs Toggl Track to Kimai migrations at a fixed price: the exports, the setup of time zones, currencies, rates and teams, the test import, the reconciliation per customer and month, SAML sign-on and the cutover. Where your requirements need a paid Kimai plugin, the subscription is named in the proposal. Then we operate Kimai for you under a contract that, from the Business plan, includes a monthly availability commitment with service credits. See migration services for what the fixed price covers, or tell us how your team tracks time today and we will scope it.
Questions
Can Kimai import our Toggl Track history?
Which Toggl Track plan do we need for the export?
Do our hourly rates come across?
Do people keep their Toggl passwords?
Is Kimai open source?
How long does a Toggl Track to Kimai migration take?
Let us run the move for you
An inventory, a parallel run and a cutover plan, at a fixed price. Then we operate the app.
- Go deeperSaaS migrationA fixed-scope migration off Google Workspace, Microsoft 365, Zapier, Airtable and ChatGPT to open-source apps, with a parallel run and a cutover plan.
- CheckManaged operationsPatching, daily encrypted backups, monitoring and incident response for your open-source apps, under an SLA with an availability commitment of up to 99.9%.
