Restore a Project Export into Jira Cloud

Last updated 10 November 2026 · restore script 1.0.0

Project Export saves one Jira project to a zip you keep. This page explains how to put it back: the restore script rebuilds it as a new project on the same Jira Cloud site or on a different one, from the file alone. It never reads the site the export came from.

Download the restore script (project-export-restore-1.0.0.zip)

What you need

• Python 3.8 or later. macOS and Linux have it; on Windows, install it from python.org. The script uses only Python's standard library: nothing else to install.
• Jira admin on the target site (the Administer Jira permission). The restore creates statuses, workflows, custom fields and a project, which only a Jira admin can do.
• An API token for your Atlassian account: create one at id.atlassian.com/manage-profile/security/api-tokens. The script runs as you, with your own token, from your computer. Nothing goes through us.
• The whole export. Exports over 500 MB come as several files (part-000.zip, part-001.zip, ...). Download every part into one folder. A file saved through "Open link" may have a long random name: that's fine, keep it in the folder.

1. Set your site and token

macOS or Linux:

export ATLASSIAN_SITE=https://yourcompany.atlassian.net
export ATLASSIAN_EMAIL=you@yourcompany.com
export ATLASSIAN_API_TOKEN=paste-your-token

Windows (PowerShell):

$env:ATLASSIAN_SITE="https://yourcompany.atlassian.net"
$env:ATLASSIAN_EMAIL="you@yourcompany.com"
$env:ATLASSIAN_API_TOKEN="paste-your-token"

ATLASSIAN_SITE is the site you restore into.

2. Dry run: see the plan, write nothing

Pick a key for the new project (2 to 10 capital letters, not used on the target), then:

python3 restore.py WEB-export-2026-11-10.zip --key WEBR --dry-run

Pass the merged zip, the part files, or the folder that holds them:

python3 restore.py ~/Downloads/web-export/ --key WEBR --dry-run

The dry run reads the target site and prints:

• the project it would create, and whether the key and name are free;
• the work item types, statuses, workflows (one per work item type, as in your source project), custom fields and options, link types, versions, components, boards and sprints it would create, and which ones it reuses because the target already has them by name;
• the target's own check of the workflows;
• which people in the export aren't on the target site;
• priorities or resolutions the target lacks, attachments that aren't in the file, missing parts;
• what will be lost (below), and an estimate of the time it takes.

Nothing is written. Fix what it lists (invite missing people, add missing priorities) and run it again until you are happy.

3. Restore

python3 restore.py ~/Downloads/web-export/ --key WEBR --name "Website (restored)"

It asks once before writing, then works through ten steps with progress as it goes: project, work item types, statuses and workflows, custom fields, versions and components, work items, then each item's status, comments, worklogs, attachments, history and watchers, then parents and links, boards and sprints, and rank order.

Speed: Jira answers about one request every 1 to 2 seconds, so a 60-item project takes 10 to 20 minutes and a project with several thousand work items takes several hours. You can leave it running.

If it stops (network, laptop asleep, Ctrl-C, a refused request), run the same command again. The script keeps a log, restore-log-WEBR.json, and continues from where it stopped without creating anything twice.

What the restore keeps

Tested on a project with epics, sub-tasks, links, worklogs, a scrum board with a closed and an active sprint, six kinds of custom field and a custom status, restored into a different, empty Jira Cloud site:

• work item keys (WEB-12 becomes WEBR-12; gaps in the numbering are kept too);
• summary, description, type, status, resolution, priority, labels, assignee, due date, original estimate;
• components and versions;
• custom fields and their options (tested: select, multi-select, checkboxes, user picker, number, rich text, date; text, URL, labels and cascading select are handled the same way);
• the workflow of each work item type, with its statuses and transitions;
• epics, parents and sub-tasks; links between work items in the project;
• comments (text and formatting), worklogs (time spent and start), attachments (every file in the export), watchers;
• boards, sprints with their names, dates, goals and state, and rank order.

What Jira can't take back, and how the restore keeps it instead

Jira's API doesn't let anyone write these, so no restore tool can:

Lost in Jira	Kept instead
Created, updated and resolved dates	They become the restore date. The originals are in the export's JSON.
Comment and worklog authors and comment dates	They become you. Each restored comment and worklog starts with an italic line: "Originally by Ana Silva on 2026-03-14 09:12 UTC".
Attachment authors and upload dates	They become you and the restore date; the files are the same.
Reporter	Kept if you have the Modify Reporter permission in the new project. Jira Free sites can't grant it: there you become the reporter, and the original is in the export JSON and the history file.
History (who changed what, when)	Each work item gets a history-<KEY>.csv attachment: when, who, field, from, to.
Board columns, swimlanes, quick filters	No public API writes them: boards come back with the default columns for their workflow. Set them again by hand.
People not on the target site	Their assignments and watches are left empty; their names stay in the comment lines and history files. Invite them before restoring to keep them.

Not part of a project export at all: automation rules, permission, notification and screen schemes, dashboards and filters other than the board's.

Common questions

Can I restore over the original project? No. The restore always creates a new project, so it can't damage the one you have. Restore under a new key, check it, then archive or rename as you like.

Same site or another site? Both. On the same site it reuses the statuses and fields that are already there by name. On another site it creates what's missing.

Team-managed projects? They are restored as company-managed projects: their fields and workflow become site-wide ones on the target.

Workflow rules. Conditions, validators and post functions are copied. If the target refuses one (for example, a rule naming a group that only exists on the old site), the workflows are created without rules and the log lists what was dropped.

Deleted work items. To keep key numbers, the restore creates and deletes a placeholder for each gap. That needs the Delete work items permission in the new project; without it, placeholders are left and listed at the end for you to delete.

Check the result. verify.py compares the original and the restored project field by field, when your account can read both: python3 verify.py --source-site https://old.atlassian.net --log restore-log-WEBR.json.

Something failed? Every problem is listed at the end and in the log, with Jira's own message. Send the log to support@opsfixes.com (it contains keys and field names, no passwords or tokens) and we'll help.