Notes and project management

How to move from Jira to Linear: API or CSV import, and what maps to what

SwitchTo HQ · Updated 18 October 2026 · Notes and project management · How we write

Linear has a dedicated importer for Jira that brings Jira projects across as Linear teams. You can import using Jira API credentials or a CSV export, and you can keep a team's work synced back to Jira while the rest of the organisation is still using it. This guide walks through the choices you need to make, based on Linear's Jira import documentation and its general import guide.

Who can run the import

Linear says imports can only be started by workspace admins. For the API method you also need admin permissions in the source Jira project. Check both before you plan the day.

Choose an import method

Linear offers two in-product methods for Jira, plus a command-line tool:

Method	Advantages	Drawbacks
API import	Retains the most data, and allows Jira Sync to be switched on at the end of the import	Needs admin permissions in the source Jira project
CSV import	Doesn't need high Jira permissions, and can import many Jira projects at once if you don't need issue ID matching	Issues can't be synced with Jira; they are static copies as of the import
Linear CLI	Available for scripted imports	Linear doesn't recommend it for Jira: it imports less data, doesn't label imported issues and isn't easy to delete if you need to start again

Linear says both in-product methods label imported issues "Migrated", can be deleted from Import/Export settings within seven days, and can support matching issue IDs. That seven-day window is useful: you can do a trial import, check it, delete it and run it again with better settings.

How Jira fields map to Linear

Linear publishes a mapping table. The main points are:

Jira	Linear
Project	Team
Summary	Title
Description	Description, converted to Markdown
Assignee and creator	Assignee and creator (best-effort match)
Priority	Priority
Issue type, type and components	Labels
Epic	Project
Parent and child issues	Parent issue and sub-issue
Status	Status (best-effort conversion)
Comments, estimates, due dates, created dates	Carried across
Images	Image files
Non-image attachments	Links pointing back to the original file in Jira

Two limitations matter for most teams:

Custom fields are not imported. Anything not in the table, including Jira custom fields, stays behind. If you rely on a custom field such as "Customer" or "Severity", decide before importing whether to turn it into a Linear label or record it some other way.
Non-image attachments stay in Jira. They arrive as links to the files in Jira. If you plan to close your Jira site, download any attachments you need to keep before you do, or those links will stop working.

Linear also notes that API credentials must be supplied at import time for files to be fetched.

Before you import: decide on teams and statuses

Linear's general import guide recommends choosing an existing team or creating a new one during the import. You can import into a top-level team or a sub-team with its own workflow statuses, but not into a sub-team that inherits its statuses from a parent team.

Because statuses are converted on a best-effort basis, it helps to set up your Linear team's workflow first, with statuses that roughly match how your Jira board works (for example Backlog, Todo, In Progress, In Review, Done).

Running the import

The steps follow the same pattern for each source:

Set up. Provide a Jira API token or upload your CSV, then choose an existing Linear team or create a new one.
Review. Linear shows the issues, projects, labels and users it has found.
Choose what to import. You can import active issues only, or broader sets that include stale, completed or all issues. Bringing only active work across keeps the new workspace tidy; older issues can stay in Jira or in an export.
Map users. For each Jira user, choose not to import them, create a new user from an email address, or map them to an existing Linear user.
Confirm. Check the summary and select Finish.

Keeping Jira in sync during a transition

If one team is moving to Linear while the wider organisation still uses Jira, Linear's Jira Sync can reflect that team's work back into Jira. According to Linear's documentation:

Configure the Jira integration before your first import if you want synced issues.
During the import, make sure Sync issues after import is selected.
Issues imported from CSV can't be synced.
Linear's Jira integration page notes that the two tools have different hierarchy rules (Jira uses Epic, then Story, Bug or Task, then Sub-task), so some changes made in Linear can cause sync discrepancies.

Checking the result

After the import:

Compare issue counts per project against the number of issues in each Linear team.
Open a sample of issues and check descriptions, comments, images and attachment links.
Check that epics have become projects and sub-tasks have become sub-issues.
Search for issues that should have a custom field value and add it as a label if needed.
Update any integrations, such as GitHub or GitLab links, so pull requests reference the new Linear issue identifiers.

If something looks wrong, delete the import within the seven-day window and run it again. Linear warns that re-importing from the same source into the same team without deleting the first import will skip issues that were already imported.

Checklist

Confirm you are a Linear workspace admin and, for API imports, a Jira project admin.
Choose API import (more data, sync possible) or CSV (fewer permissions, no sync).
Set up Linear team statuses before importing.
Record any custom fields you need, and download non-image attachments if Jira will be closed.
Import active issues first, map users, and check the result.
Use the seven-day delete window to redo the import if needed.