Anki .apkg Import Errors and How to Fix Them
A package import is supposed to be the easy path: double-click, and the deck is there with its note type, its templates and its media. When it is not, the message on screen rarely names the real cause. Here is what each failure actually means, in the order you should check them.
On this page
A clean import, step by step
Check which package you actually have
- A .apkg is a deck package: it adds a deck, its notes and the note type they need. This is what shared decks and our exports are.
- A .colpkg is a collection package, meant for backup and for moving a whole collection to another device. Importing one deletes every card you currently have and replaces it with the file's.
- If the file ends in .apkg.zip, .apkg.txt or just .zip, the browser renamed it on download. Rename it back to end in .apkg before doing anything else.
- A truncated download looks exactly like a corrupt file. Compare the size on disk with the size the source advertised before you blame Anki.
Open it through File, Import
- In the desktop app choose File, then Import, and pick the package. If several profiles exist, the deck lands in whichever one is open.
- AnkiDroid and AnkiMobile both open a .apkg directly, so a deck can be imported on the phone and synced from there.
- Importing into a collection that already has cards is additive. A .apkg never wipes anything, whatever the deck description claims.
Read the import options before confirming
- 'Import any learning progress' controls whether the author's review history comes with the deck. Leave it off for a shared deck: you want the cards, not someone else's intervals, leech flags and marked tags.
- The update behaviour decides what happens to notes you already imported once before. You can let newer notes overwrite your edits, never update existing notes, or merge note types.
- Merging note types keeps every field and template from both sides, but it requires a full sync afterwards, so do it when you can afford to upload the collection.
Read the summary Anki shows
- Notes counted as updated rather than added mean this package has been imported here before. Anki recognises them from that earlier import, not from the text on the front.
- Skipped notes usually mean the same package is already fully present, or the note type changed since the last import so the existing notes could not be updated.
- Fewer cards than notes is normal: a note with one card template makes one card, and a note type with two makes two.
Check the media separately
- Run Tools, then Check Media. It lists files referenced by notes but missing from the folder, and files sitting in the folder that no note uses.
- Missing entries after a fresh import mean the package shipped without its media, which is an export-side choice, not something the import can recover.
- Filenames beginning with an underscore are skipped by the check on purpose, so template assets do not show up as unused.
Undo before you tidy up by hand
- Edit, then Undo Import, right after the import, reverses the whole thing.
- Later, delete the deck the package created, or search the Browse window for the tag it imported with and delete that selection.
- Before an import that updates existing notes, export your own deck with scheduling included. That copy is the only thing that makes an overwrite reversible tomorrow.
The error you are looking at
Six symptoms cover nearly every failed package import. Find yours, and the cause is in the same paragraph.
You imported a .colpkg rather than a .apkg. A collection package is a replacement, not an addition: importing one deletes all of your current cards and puts the file's collection in their place. Media files survive unless you delete them with the media check tool. Recover from an automatic backup, and from now on check the extension before opening anything called 'my anki backup'.
In almost every case the file is not a .apkg any more. A .apkg is a zip container, and inside it there has to be a collection file. If you rename a copy to .zip, open it, and find no collection.anki2, collection.anki21 or collection.anki21b inside, the download failed or the browser wrapped it in something else. Download it again rather than hunting for an import setting.
Newer Anki writes the collection inside the package in a compressed format that older clients cannot read. Updating your Anki is the clean fix. If you cannot update, the person exporting can tick 'Support older versions' when they create the package, which produces a legacy-compatible file that is larger and slower to make.
The author exported with scheduling included, so you inherited their review history. Reimport with 'Import any learning progress' unchecked, which also drops their leech and marked tags. For cards already in your collection, select them in the Browse window and use Set Due Date.
Two different causes. If the notes were skipped, the package matches what you already have. If they were skipped only after the author reworked the deck, the note type structure changed, and Anki will not update notes across a changed note type: new notes still come in, existing ones stay as they are. The merge option added in 23.10 is what reconciles the two, at the price of a full sync.
The package was exported without its media. That is a checkbox on the export side, and nothing on the import side can bring back files the file never contained. Tools, Check Media names every missing file, so you can see immediately whether they were dropped in the export or lost afterwards.
When the file is the problem
Before you reinstall anything, find out whether the package is readable at all. Our Anki to Mochi converter opens a .apkg in your browser and shows you the cards it finds. If it lists your deck, the file is intact and the problem is on the Anki side, usually a version too old for the package. If it cannot find a collection inside, the download is broken and no import setting will rescue it.
If the package is genuinely damaged and you still have the source list, rebuilding is faster than repairing. The CSV to Anki converter turns a spreadsheet back into a package with its note type already set, and the file never leaves your browser. A Quizlet export goes through the Quizlet to Anki converter instead.
And if the cards themselves are gone, the Anki generator writes a fresh deck from a prompt, with translations, example sentences and pronunciation audio, and hands back a package that imports in one double-click.
Inside a .apkg
Knowing what the container holds turns most of these errors from mysteries into obvious consequences of how the format works.
Rename one to .zip and open it. There is a SQLite database called collection.anki2, or collection.anki21, or collection.anki21b in packages from recent Anki versions, where the b marks a zstd-compressed database. Beside it sit media files named 0, 1, 2 and so on, plus a small JSON file named media that maps each of those numbers back to a real filename. That indirection is why a deck can carry a file called mañana.mp3 across operating systems that disagree about accents in filenames.
Inside the database a note stores all of its fields in a single column, joined by the 0x1f separator, and the note type stored alongside says what those positions are called and how they render. A CSV has neither half: it carries the text but not the names, not the templates and not the styling, which is why every CSV import asks you to reconstruct the mapping by hand and every .apkg import does not.
Notes in a package carry an identity that travels with them, so Anki recognises a note it imported from an earlier version of the same deck and updates it rather than adding a twin. This is the opposite of the CSV path, which matches on the first field. It is also why a shared deck can ship corrections months later and land them on your copy, and why an author who rebuilds a deck from scratch breaks that chain and gives everyone duplicates.
The option exists because the package format changed. Ticking it writes the collection in the legacy uncompressed form that older clients can still read, at the cost of a bigger file and a slower export. It is the right choice when you are publishing a deck to strangers whose Anki versions you cannot know, and the wrong one for a package you are moving between two machines you control.
Undo Import covers you until you close Anki. Past that, the only thing that helps is a copy made before the import. Export your own deck as a .apkg with scheduling included, or lean on the automatic backups, which are collection packages. Note the asymmetry: your safety net is a .colpkg, and restoring it replaces everything, which is exactly the behaviour that made it dangerous when it arrived by accident.
Premium access includes:
Frequently asked questions
A .apkg is one deck and everything it needs, and importing it adds to your collection. A .colpkg is a whole collection, and importing it replaces yours. Both are produced by Anki's export screen, which is why they are so easy to confuse.
No. It adds notes, and it updates only those notes you imported from an earlier version of the same package. Cards you made yourself are not touched.
Yes. AnkiDroid and AnkiMobile both open a .apkg directly, which is the practical reason to convert a word list to a package rather than a CSV when the phone is where you study.
Edit, then Undo Import, immediately after. Later, delete the deck it created, or select the imported cards by tag in the Browse window and delete them there.
Only if the person exporting chose to include it, and only if you accept it on import. For a shared deck you almost always want the cards without the history, which is what leaving 'Import any learning progress' unchecked gives you.
Keep reading
Related guides that build on what you just read.