# How to migrate from Jira to Linear: a step-by-step guide

> A practical plan for moving from Jira to Linear: what to clean up, how concepts map, which import method to choose, and how to cut over without losing history.

Published October 20, 2026 · https://jira-to-linear.com/guides/migrate-jira-to-linear/

Switching from Jira to Linear is usually a quick decision. Moving years of issues, comments and files is not. This guide walks through a migration plan that works for teams of five and for teams of five hundred: what to decide up front, what to clean up, which import method fits, and how to switch over without a week of "where did that ticket go?".

## 1. Decide what a finished migration looks like

Write down, before touching any tool, what has to be true on the day you switch:

- **Scope.** Which Jira projects move, and how far back? All history, or only issues updated in the last year?
- **What must survive.** Issue keys, comments, attachments, pull request links, sprints, fix versions, watchers. Rank them — they decide which import method you can use.
- **Owner and date.** One person owns the migration end to end. Pick a cut-over date and work backwards from it.
- **How long Jira stays around.** Read-only for 30 days? 90? Forever as an archive? This decides how much you can afford to leave behind.

Teams that skip this step usually discover on cut-over day that "we'll keep Jira for reference" means paying for both tools for a year.

## 2. Take inventory of your Jira site

You can't plan a move without knowing what's in the boxes. Collect, per project:

| What                     | Why it matters                                                         |
| ------------------------ | ---------------------------------------------------------------------- |
| Project key and name     | Becomes the Linear team key — `ENG` should stay `ENG`                  |
| Number of issues         | Drives import time and, for paid tools, price                          |
| Attachment storage       | Large files take the longest and break first                           |
| Custom fields in use     | Most importers drop them; decide where each one goes                   |
| Workflows and statuses   | Linear has one workflow per team; Jira can have many per project       |
| Sprints and fix versions | History you'll want for retrospectives and release notes               |
| Integrations             | GitHub, GitLab or Bitbucket, Slack, Confluence links, automation rules |

A JQL search such as `project = ENG` gives you issue counts per project. Your Jira admin can tell you total attachment storage.

## 3. Clean up before you move

Everything you import, you'll have to live with in Linear. A few hours of cleanup pays for itself:

- **Close or archive stale work.** Issues nobody has touched in two years rarely need to be open in Linear. Import them as completed or canceled, or leave them out.
- **Merge duplicate labels and components.** `frontend`, `Frontend` and `FE` should become one label before the import, not after.
- **Decide on every custom field.** For each one, choose: turn it into a label, append it to the description, or drop it.
- **Simplify statuses.** Seven Jira statuses that mean "in progress" should become one or two Linear workflow states.

## 4. Map Jira concepts to Linear

Linear is deliberately simpler than Jira, so some concepts merge and a few disappear. The short version:

| Jira               | Linear                                   |
| ------------------ | ---------------------------------------- |
| Project (with key) | Team (with the same key)                 |
| Epic               | Project or parent issue                  |
| Story, task, bug   | Issue, with the type as a label          |
| Sub-task           | Sub-issue                                |
| Sprint             | Cycle going forward; history as projects |
| Fix version        | Release                                  |
| Component          | Label                                    |
| Watchers           | Subscribers                              |

The [Jira to Linear mapping guide](https://jira-to-linear.com/guides/jira-to-linear-field-mapping/) covers every field, including statuses, priorities and custom fields.

## 5. Choose an import method

There are five realistic ways to get your data across:

1. **Linear's built-in Jira importer.** Free and fast for the basics: titles, descriptions, statuses, comments and images. It runs once, and it leaves fix versions, sprints, pull request links, watchers, custom fields and most non-image files behind. See [what Linear's Jira importer leaves behind](https://jira-to-linear.com/guides/linear-jira-importer-limitations/).
2. **CSV export and import.** Works for small, simple projects. You lose comments' structure, attachments and links, and CSV imports can't be kept in sync.
3. **Linear's Jira Sync integration.** Keeps new issues flowing between the two tools. It's a bridge for teams running both, not a way to move history.
4. **A dedicated migration tool** such as [Jira-to-Linear-importer](https://jira-to-linear.com/), which imports everything above, keeps issue keys and can sync incrementally until you switch.
5. **Your own scripts.** Possible, and more work than it looks: rich-text conversion, attachment uploads, rate limits, user matching and restarts each take a day or more.

Pick the cheapest method that keeps everything on the "must survive" list from step 1.

## 6. Back up Jira

Whatever method you choose, take a full backup of your Jira site before the first import, including attachments. Jira Cloud's backup manager can create one. Store it somewhere that will outlive your Jira subscription — it's your archive once Jira is gone.

## 7. Run a test import

Import into a test team (or a separate test workspace) first, then check a sample of 20 issues by hand:

- Are descriptions readable, with headings, code blocks, tables and mentions intact?
- Do attachments open — from Linear, not from a link back to Jira?
- Are statuses, assignees, priorities and estimates right?
- Do parent issues, sub-issues and relations point to the right places?
- Do comments keep their order and authors?

Fix the mapping and run it again. Two or three rounds are normal.

## 8. Plan the cut-over

There are two common strategies:

- **Freeze and move.** Make Jira read-only on a Friday, import over the weekend, start Monday in Linear. Simple, but it needs a quiet weekend and a single big import that must work the first time.
- **Import early, then sync.** Import everything a week or two ahead, keep syncing changes while the team works in Jira, then switch on a normal workday. Less risk, but it needs a tool that supports incremental sync.

Either way, cut over between sprints so nobody has to move work mid-sprint.

## 9. Switch over

On the day itself: freeze Jira, run the final import or sync, spot-check, and announce the switch with links to the new teams. The [migration checklist](https://jira-to-linear.com/guides/jira-to-linear-migration-checklist/) has every step.

## 10. After the move

- Point GitHub or GitLab, Slack and any automation at Linear, and turn off Jira webhooks and automation rules.
- Update links in docs and wikis. If your issue keys are unchanged, a single search-and-replace of the Jira URL prefix fixes them — see [keeping your Jira issue keys](https://jira-to-linear.com/guides/keep-jira-issue-keys-in-linear/).
- Keep Jira read-only for a few weeks, then export the final backup and cancel.
- Collect feedback after two weeks. Most teams adjust labels and workflow states once they've lived in Linear for a sprint or two.