Import Jira Issues from CSV: A 5-Step Setup Guide for 2026
Need to import Jira issues without errors? Follow this jira import issues csv guide to map fields, prevent duplicates, and verify results. Read now.
A Jira CSV import can move hundreds of issues quickly, but a mismatched column or user account can leave important details behind. A rushed import may create duplicate work, break parent-child links, or put issues in the wrong project. Then you have to untangle the results by hand.
But here's the truth: a clean import depends less on speed than on preparation. I’ll walk you through five practical steps, from organizing your CSV columns to checking the imported issues. You’ll also learn how to handle common mapping problems and what to verify before importing a large batch. The process works across Jira Cloud and Data Center, though menu names and available options can vary by version. Start with a small, representative batch, and you can catch problems before they affect the whole project.
How to import Jira issues from CSV in five steps
To import Jira issues from CSV, prepare your columns, open Jira’s external system import, configure the CSV settings, map fields, and review the results. You may need Jira administrator permissions to access the importer.
-

Step 1: Prepare and check your CSV columns
Give every column a clear header, such as Summary, Issue Type, Assignee, Priority, and Description. Keep each issue on its own row, and use consistent values throughout.
Check that every issue has a summary and a valid issue type. Confirm project keys, usernames, dates, and priority names match the values Jira recognizes. Save the CSV using UTF-8 encoding when possible.
For example, use “Bug” consistently rather than mixing “Bug,” “Defect,” and “Error.” Consistent values make field mapping easier and reduce import warnings.
-
Step 2: Open Jira’s CSV importer
In Jira, open Settings, then System, and look for External system import or the CSV import option. The exact wording and location depend on your Jira version and permissions.
If you cannot see the importer, ask a Jira administrator to check your permissions or run the import. Before importing into a shared project, agree on a suitable time with the project team.
-
Step 3: Select the CSV and configure import settings
Choose the CSV option and provide the CSV you prepared. Set the character encoding and delimiter to match its contents. For many CSVs, the delimiter is a comma, but exported settings may differ.
Check the preview or parsing options Jira provides. If descriptions contain commas, quotation marks, or line breaks, confirm they remain together in the correct cell rather than shifting into other columns.
Here's why: a delimiter mismatch can make one issue look like several incomplete columns. Correcting that setting before import is much easier than fixing every affected issue later.
-
Step 4: Map CSV columns to Jira fields
Match each CSV header to its corresponding Jira field. Map fields such as Summary, Description, Issue Type, Assignee, Priority, Labels, and due dates where available.
For custom fields, confirm the destination project has the field configured and that its values match the accepted options. Map user names to existing Jira accounts. If Jira cannot resolve a user, correct the value or choose an appropriate fallback.
Leave columns unmapped when you do not need them in Jira. Avoid mapping two different columns to the same field unless you understand how the importer handles those values.
-
Step 5: Review, import, and verify the issues
Review the project, field mappings, and validation messages before starting the import. Fix errors such as missing summaries, invalid issue types, or unrecognized users. Import a small sample first when you have many issues or complex custom fields.
After the import, open several issues and check their descriptions, assignees, priorities, labels, and dates. Compare the number of imported issues with the number of rows you expected to import.
The best part? A quick review can reveal a problem while it is still limited to a small batch. If the sample looks right, continue with the remaining issues and check the final import summary.
Prepare the CSV before you start
Organize the columns around the Jira fields you actually need. A basic import might include Summary, Description, Issue Type, Priority, Assignee, and Labels. Add custom fields only when the destination project is ready to accept them.
Keep the formatting predictable. Use one date format throughout, avoid extra spaces in project keys, and check that commas inside descriptions are handled correctly. For example, a description such as “Check the login, billing, and export pages” must stay in one cell.
Let me explain: Jira can map a column only when it can read the column consistently. If the CSV opens with shifted values or broken line breaks, correct the formatting before you begin the import.
Map values carefully to Jira fields
Field mapping connects each CSV column to a Jira field. The header names do not always match Jira’s field names, so inspect the mapping screen instead of assuming Jira will interpret every column correctly.
For example, a column called “Owner” may need to map to Assignee. A column called “Work type” may need to map to Issue Type. If the intended field is unavailable, check the project configuration and your permissions.
| CSV column | Possible Jira field | What to check |
| Title | Summary | Every issue has a concise summary. |
| Owner | Assignee | The value matches an existing Jira account. |
| Work type | Issue Type | The value is available in the destination project. |
| Target date | Due Date | The date format matches the importer setting. |
| Tags | Labels | Values use a consistent separator and spelling. |
You might be wondering: what should you do with columns Jira does not recognize? Leave them unmapped if they are not needed, or configure an appropriate custom field before importing.
Handle issue links and parent-child relationships
Related issues may need extra planning. A CSV with parent tasks, subtasks, or issue links should include a consistent way to identify how those records connect. Jira’s supported relationship fields can vary by importer and version.
Check the CSV importer’s available fields before relying on a particular parent or issue identifier. Test the relationship mapping with a few representative issues, then confirm the parent and child appear correctly in Jira.
For example, import one parent task and two subtasks as a test. If Jira creates all three as independent issues, stop and adjust the mapping before importing the rest.
Verify the result after the import
Do not rely only on a successful completion message. Open a sample of imported issues and inspect the fields your team depends on. Check descriptions, account assignments, dates, priorities, labels, and custom fields.
Compare the imported issue count with your expected total. Review warnings and skipped rows, then investigate any unexpected differences. If the issues will feed a sprint or release plan, confirm their project and workflow status before the team starts work.
A short verification pass can prevent a longer cleanup. For instance, spotting a date-format issue immediately can save you from correcting due dates across an entire project.
CSV issue migration solution: ONES.com
ONES.com brings project management and knowledge management together in one platform powered by ONES Assistant. ONES Project is its project management product and a Jira alternative; ONES Wiki is its knowledge base product and a Confluence alternative. They are sold separately.

If a CSV import is part of a broader move away from Jira, think about the workflows your team must preserve after migration. ONES.com offers Cloud, On-Premise, Private Cloud, and Air-gapped deployments, with full feature parity between its cloud and self-hosted versions. A free plan supports up to 30 seats.
Core capabilities
- Fragmented project work: ONES Project provides project management in a unified platform, helping teams coordinate work without switching between disconnected systems.
- Jira workflow expectations: Jira-compatible workflows help teams retain familiar processes while adjusting their project setup.
- Limited reporting visibility: Built-in reporting gives teams a clearer view of project progress without depending on as many add-ons.
- Changing team processes: Custom workflows and fields let teams reflect their approval stages, issue types, and tracking needs.
- Sprint planning needs: Sprint management supports planning and tracking work across development cycles.
- Repetitive manual actions: Automation can handle routine workflow tasks, reducing repeated updates by team members.
- Restricted network requirements: On-Premise, Private Cloud, and Air-gapped deployments give organizations deployment choices for different infrastructure and security needs.
- Separate project and knowledge needs: ONES Project and ONES Wiki can address project management and knowledge management separately, so teams can choose the product that fits their needs.
Application scenarios
A software team moving a backlog from Jira can first import issues, then configure compatible workflows, sprint management, and reports in ONES Project. A pilot project helps the team confirm its process before broader adoption.
An organization with restricted network requirements can evaluate an Air-gapped or other self-hosted deployment. Full feature parity between cloud and self-hosted versions helps teams choose deployment options without giving up platform capabilities.
ONES.com is most relevant when you are evaluating the project environment that will support your team after a migration. It does not remove the need to check CSV formatting and field mappings before importing issues.
Common challenges and practical fixes
Jira cannot recognize an assignee
Problem: The CSV contains a name or email address that does not match a Jira account Jira can resolve.
Solution: Check the account value and the importer’s expected format. Correct the value or leave the assignee unmapped and assign the issue after import.
Custom-field values are rejected
Problem: Jira reports that a value is unavailable or invalid for a custom field.
Solution: Confirm the field is available in the destination project and that each value matches an allowed option. Test with a small batch before importing all issues.
Descriptions shift into neighboring columns
Problem: Commas, quotation marks, or line breaks make the imported columns appear misaligned.
Solution: Check the CSV delimiter and text-quoting settings. Inspect the parsed preview and correct the formatting before you start the import.
The issue count does not match expectations
Problem: Jira imports fewer issues than expected, or some rows appear to have been skipped.
Solution: Review the import summary and validation messages. Check for blank summaries, invalid issue types, and malformed rows, then correct and import the missing issues.
FAQs about importing Jira issues with CSV
Do I need Jira administrator permissions to import issues?
Often, yes. Jira’s CSV importer may require Jira administrator permissions, particularly when you use the external system import options. Access can vary by Jira version and setup. If the import option is missing from your settings, ask a Jira administrator to confirm your permissions or run the import for you.
Which columns should I include in a Jira CSV import?
Include the fields needed to create and manage the issues, such as Summary and Issue Type, plus fields like Description, Assignee, Priority, Labels, or Due Date when required. The exact fields depend on your project configuration. Start with a small set, then add custom fields after confirming Jira can map them correctly.
Can I import subtasks and parent issues through CSV?
It may be possible, but the available relationship fields and behavior can vary by Jira version and importer. Check the importer’s field options before preparing a large batch. Test a parent issue and a few subtasks first, then inspect the resulting hierarchy in Jira before continuing.
What should I do if Jira rejects some rows?
Read the validation messages and import summary to identify the rejected rows. Common causes include a missing summary, an issue type that is not available in the project, an invalid custom-field option, or an account Jira cannot resolve. Correct the affected values, then retry those issues and verify the final count.
Conclusion
A reliable Jira CSV import starts with consistent columns and ends with a careful check of the created issues. Prepare the fields, configure the importer, map each value deliberately, and test complex relationships before importing a large batch.
But here's the truth: skipping preparation often costs more time than the import itself. Check a small sample, resolve warnings, and confirm the issue count and key fields. If you are also considering a new project environment, compare how its workflows, reporting, deployment options, and team setup fit the way you work.