Import Excel to Jira CSV: Sample File and Import Steps

How-to basics · Updated November 18, 2026

To import Excel issues into Jira, arrange one issue per spreadsheet row, save the sheet as a CSV UTF-8 file, then use Jira’s CSV issue importer to map the columns to Jira fields. Here is a usable starter sample: copy it into Excel, replace the example values, save as CSV UTF-8, and import it into the intended Jira project.

Sample Excel and CSV layout

Use a single header row with recognizable field names and one row for each issue. This sample includes a project key so the destination is explicit; replace WEB with a project key that exists in your Jira site.

Project key,Issue Type,Summary,Description,Priority,Labels,Due date
WEB,Task,Update onboarding guide,Revise screenshots and links,Medium,onboarding,2026-12-15
WEB,Bug,Checkout fails with expired card,"Steps: select an expired card, then submit payment.",High,payments,2026-12-18
WEB,Story,Add account recovery,Let users request a password reset,Medium,account,2026-12-22

In Excel, put each heading in its own cell across row 1 and each issue on a separate row below it. The sample’s second description contains a comma, so it is enclosed in double quotes in CSV. CSV files use commas to separate fields; quotes keep a comma that belongs to a description from being mistaken for a column break.

The names in the header row are suggestions, not a guarantee that every Jira project has every field. During import, Jira asks you to associate CSV columns with fields available in the destination project. The issue type, priority options, date format, and required fields can vary by Jira configuration. If a value is not offered or does not match a configured option, correct the data or select a valid mapping before importing.

Prepare the workbook before exporting

Clean the sheet before creating the CSV. Remove title rows, blank columns, totals, notes, and formatting-only content. Keep the actual header row at the top, and check that each issue has a Summary. Avoid merged cells: they can make it unclear which issue a value belongs to. If a field is optional and has no value for an issue, leave that cell empty rather than entering words such as “none” or “not applicable,” unless those words are genuinely intended data.

  • Use one worksheet for the import data. A CSV export contains the active sheet, not every worksheet in the workbook.
  • Keep a separate copy of the original Excel workbook. It preserves formulas, formatting, and other sheets that CSV cannot store.
  • Check for formulas in fields you plan to import. Excel exports the displayed formula results as values, not the formulas themselves. Confirm those results are current and correct before saving.
  • Use consistent spelling and capitalization for controlled values such as issue type and priority. Jira may reject or fail to match a value that is not an available option.
  • Check for commas, quotation marks, and line breaks in descriptions. Proper CSV exporters quote fields when needed; do not manually split a description into extra columns.

In Excel for Microsoft 365 on Windows, use File > Save As > Browse, choose CSV UTF-8 (Comma delimited) (*.csv) in the file-type list, and save. Excel may warn that CSV does not support multiple worksheets or some workbook features; confirm the CSV choice for the import copy. On a Mac, use File > Save As and select the CSV UTF-8 format in the file-format control when available. Menu wording can differ by Excel release. If you use Excel for the web, download or save a CSV copy and inspect that file before importing.

How Jira’s CSV import works

Jira reads the CSV as a set of rows and columns, then asks you to map columns to issue fields. The importer does not simply recreate an Excel workbook inside Jira. It creates Jira issues from the data you identify, subject to your permissions, project settings, and any required fields. Spreadsheet colors, formulas, charts, cell comments, and multiple tabs are not imported as issue data.

In Jira Cloud, the administrative CSV import is generally found under Settings > System > External system import > CSV. Access and wording can differ by Jira version and permissions; a Jira administrator may need to run or enable the import. Follow the importer’s prompts to choose the file, configure separators and other file options if requested, map fields, and review the import before starting it. Jira Data Center and older Jira interfaces may present a different route or labels, so use the importer available on your installation.

When mapping, match each CSV heading to the appropriate Jira field. For example, map Summary to Summary, Description to Description, and Issue Type to the issue-type field. Map Project key if the importer offers that field and you are using it to identify the destination. If you import into one project through a project-specific flow, the project may instead be selected in the import setup. Do not assume the header alone determines the mapping; verify the choices shown by Jira.

Choose fields and values carefully

Start with the smallest useful set of fields. Summary and issue type are central to creating readable issues; descriptions, priority, labels, and due dates can be added if they are useful and supported. A smaller first import is easier to validate than a large sheet containing every possible field. You can include more fields once the basic format works.

Project-specific options matter. A project may have custom issue types, a restricted set of priorities, required fields, or workflows that affect what can be created. If a field is mandatory in the project, include it or arrange to supply it during the import if the importer allows. A value such as Medium is only valid if the destination recognizes that priority. Labels are often entered as plain text, but the importer’s mapping and treatment of multiple labels should be checked rather than inferred from how Excel displays a cell.

Be cautious with people fields such as Assignee and Reporter. Jira’s expected user identifier can depend on the product version, account privacy settings, and importer behavior. A person’s display name or email is not guaranteed to resolve. If you need to import these fields, confirm the accepted identifier format in your Jira environment and test with a small file. Otherwise, omit the field initially and assign users after the issues are created.

Dates, descriptions, and special characters

Date interpretation is a frequent source of errors. A date such as 03/04/2026 could mean March 4 or April 3 depending on regional conventions. Use an unambiguous format, such as the sample’s year-month-day form, and set or confirm the date format in the importer if it asks. Ensure the Jira field is actually a date field and that its configuration accepts the supplied value.

Descriptions can contain commas, quotation marks, or line breaks. CSV allows these values when the field is quoted correctly, and Excel’s CSV export normally handles that quoting. A quotation mark inside a quoted CSV field is represented by two quotation marks. Avoid editing the CSV by hand in a way that removes those protections. For non-English text, choose UTF-8 when saving and check the resulting file if names or characters look corrupted in a text editor.

Attachments are not embedded by putting an Excel file path in a cell. CSV importers may provide attachment-related options in some configurations, but that is a separate process with its own file access and formatting requirements. Check the documentation for your Jira version before planning an attachment import; do not expect a normal Description or attachment-name column to upload files.

Run a small test and verify the result

Before importing hundreds of rows, make a small test file with a few representative issues. Include a long description, a date, and any less common field you intend to map. Use the importer’s review or validation screen to check the detected columns and values. Correct warnings before proceeding, especially if the importer reports missing required fields, invalid option values, or unmapped columns.

  1. Save a backup copy of the workbook and export a test CSV.
  2. Start the Jira CSV importer and choose the correct project or project-key mapping.
  3. Map each intended column, select the appropriate date and CSV settings, and review any validation messages.
  4. Import a few issues, then open them in Jira to confirm summaries, descriptions, types, priorities, labels, and dates.
  5. Only after the test looks right, import the remaining rows and check the final import summary.

For a repeated or large import, plan how to recognize records that have already been created. Importing the same rows again can create duplicate issues unless your process and importer settings specifically match or update existing records. Keep a copy of the source file and record the import outcome. If a test creates unwanted issues, use Jira’s normal issue-management tools or ask an administrator about cleanup; do not assume the importer can automatically roll back a completed import.

Common problems and practical fixes

  • Everything appears in one column: Check that the file is comma-delimited and that the importer’s separator setting matches the file. Regional Excel settings can affect how CSV is saved; verify the exported file rather than relying on the extension alone.
  • Columns are shifted: Look for commas or line breaks in unquoted descriptions, extra separators, or inconsistent row lengths. Re-export from Excel instead of repairing complex CSV quoting manually.
  • Jira rejects an issue type or priority: Use an option available in the target project and map the column to the correct Jira field. Similar-looking text is not necessarily an exact match.
  • Dates are wrong or rejected: Replace ambiguous dates with a consistent format and confirm the format selected in the import flow.
  • Names or symbols are garbled: Export as CSV UTF-8 and check the file encoding. Re-import only after verifying that the text is readable.
  • Issues are missing required information: Check project requirements and field configuration. Add required values or ask a Jira administrator which fields must be supplied.

CSV versus other ways to create Jira issues

CSV is useful when issue data already lives in Excel, when a team is migrating a structured list, or when many similar issues must be created at once. It is straightforward to review as rows and can be prepared without writing an integration. Its limits are equally important: it is not a live connection to the workbook, and a later Excel edit does not update Jira automatically.

For a handful of issues, entering them directly in Jira may be quicker and avoids mapping work. For recurring synchronization, complex relationships, or automated updates, consider an approved integration or Jira API approach rather than repeatedly importing CSV files. Those alternatives require appropriate permissions and careful handling of credentials and data. Choose based on volume, repeat frequency, and whether Jira should receive a one-time copy or remain synchronized with another system.

Frequently Asked Questions

Can I import an Excel .xlsx file directly into Jira?
Jira’s CSV issue importer expects CSV data, not a normal Excel workbook. Save the intended worksheet as CSV UTF-8 first, then upload that CSV file.

Does importing a CSV import every worksheet in Excel?
No. CSV represents a single flat sheet. Export the relevant worksheet separately; other sheets, formatting, and workbook formulas are not part of that CSV import.

Can I import Jira issues with subtasks or links from Excel?
Some Jira CSV import flows support relationship fields, but the required columns and identifiers depend on the Jira version and configuration. Check the importer’s supported fields and test the relationship with a small sample before relying on it.

Will a second import update the issues created by the first?
Do not assume it will. A second import may create duplicates unless you configure a supported matching or update method. Confirm the available options for your Jira installation and test them before importing production data.

Why does my CSV show the wrong characters or dates?
Encoding and regional date interpretation are common causes. Save as CSV UTF-8, use consistent unambiguous dates, and check the importer’s separator and date-format settings before proceeding.

Related

Try it: the Date Difference Calculator: days, months, years and weekdays between two dates, with the DATEDIF formulas.

More in How-to basics

Sources: Function behaviour and menu paths: Microsoft Support documentation for Excel. Method & sources

Spotted an error in this guide? Let us know.