Why does GNS3 say Missing files when the image is in my Downloads folder?

The wizard does not trust the filename. It compares the MD5 checksum and size of each file with the values in the .gns3a file. If your file is a different build, or still zipped, it never matches and the version stays on Missing files.

Can I just rename my image to the filename GNS3 expects?

No. Matching is by MD5, so a renamed file with a different checksum is still not found. Use Create a new version, or tick Allow custom files, so GNS3 accepts the file you have.

Where does GNS3 store appliance images?

On a local server they go in the GNS3 images directory, by default ~/GNS3/images with QEMU, IOU and IOS subfolders. On the GNS3 VM the images path is /opt/gns3/images. The wizard uploads the file there for you when you install on the VM.

Does GNS3 give me the Cisco images an appliance needs?

No. Appliances for vendor images such as Cisco IOSv only describe the files and link to where the vendor offers them. You must get the image yourself, under your own licence, and import it.

GNS3 appliance import errors: missing files and MD5 fixes

You import a .gns3a appliance and the version you want stays on Missing files. Or you click Next and get Cannot install Cisco IOSv version 15.9(3)M12: File vios-adventerprisek9-m.spa.159-3.m12.qcow2 with checksum 61d2d7cf16c8a3efa01db6545dcecdfd not found for Cisco IOSv. Both mean the same thing: the wizard could not find a file whose MD5 checksum matches the appliance, in the places it looks.

Why it happens

A .gns3a file is a small JSON file from the GNS3 registry. It holds the template settings (RAM, adapters, console type) and a list of versions. Each version names the disk images it needs, and each image has a filename, a version, an md5sum and a filesize. The appliance does not contain the image itself. For vendor images, the download_url only points to the vendor's site.

When you reach the "Required files" page, the wizard (in gns3-gui 2.2.61) searches for each image like this:

It looks at the images already on the server you chose, such as the GNS3 VM.
It looks in the QEMU, IOU and IOS folders of your local images directory, in the folder that holds the .gns3a file, and in your Downloads folder.
It only scans the top level of those folders, not subfolders.
It accepts a file only if its size is within 10 bytes of filesize and its MD5 equals md5sum. The filename does not matter.

So the usual causes are: you have a different build of the image (a newer patch, a different train), the file is still zipped, it sits in a subfolder, or the download was cut short.

How to fix it

1. Read what the appliance expects

Open the .gns3a file in a text editor. Find the images list and the entry for the version you picked:

{
    "filename": "vios-adventerprisek9-m.spa.159-3.m12.qcow2",
    "version": "15.9(3)M12",
    "md5sum": "61d2d7cf16c8a3efa01db6545dcecdfd",
    "filesize": 57326080
}

Some versions need more than one file. The Cisco IOSv appliance, for example, also needs IOSv_startup_config.img, which it downloads from the GNS3 SourceForge project.

2. Check your image's MD5

On macOS:

md5 ~/Downloads/vios-adventerprisek9-m.spa.159-3.m12.qcow2

On Linux:

md5sum ~/Downloads/vios-adventerprisek9-m.spa.159-3.m12.qcow2

On Windows:

Get-FileHash -Algorithm MD5 "$env:USERPROFILE\Downloads\vios-adventerprisek9-m.spa.159-3.m12.qcow2"

If the hash matches, go to step 3. If it does not, go to step 4.

3. Put the image where the wizard looks

Unzip or decompress the image first. If an appliance entry has a compression field, GNS3 warns you: The file is compressed with 'zip', it must be uncompressed first (or 'gzip', 'bzip2', 'xz', '7z').

Then move the file to one of these places, at the top level:

your Downloads folder,
the folder that holds the .gns3a file,
~/GNS3/images/QEMU (or IOU, or IOS for Dynamips). On Windows this is C:\Users\<you>\GNS3\images\QEMU.

You can check the images directory under Edit > Preferences > General > Binary images ("My binary images"). Back in the wizard, click Refresh. The file status should turn green (Found locally, or Found on plus the server name) and the version should read Ready to install. You can also select the file row and click Import to pick it from anywhere.

4. Handle a different release

If your MD5 differs, renaming the file will not help. You have two clean options, both in the wizard:

Create a new version. Select the closest version, click Create a new version, give it a name, and enter your image's filename when asked. A version created this way has no checksum, so the wizard matches it by filename. The GNS3 docs describe this flow.
Allow custom files. Tick it and confirm the warning. The wizard then accepts a file with the expected filename even when its MD5 differs.

If you click Import with a wrong file, GNS3 2.2 shows:

This is not the correct file.

MD5 checksum
actual:	<your md5>
expected:	<appliance md5>

Older 2.2 releases print it on one line: This is not the correct file. The MD5 sum is ... and should be .... In GNS3 2.2.0, answering Yes there was not enough; the suggested workaround was to tick Allow custom files.

5. Install on a server that can run it

On the Server page, pick "Install the appliance on the GNS3 VM (recommended)" for QEMU appliances on Windows and macOS. If an appliance needs KVM and the server lacks it, you get The selected server does not support KVM. A Linux server or the GNS3 VM running in VMware is required. See KVM support available: False for that one.

After you confirm the version, GNS3 uploads the image to the server. Do not rush the last page: Please wait for appliance files to be uploaded means the upload is still running.

How to check it worked

The wizard ends with The appliance has been installed and a template named '<name>' has been successfully created!
The device shows up when you click Browse all devices.
On the GNS3 VM, open the shell and list the images. The GNS3 VM sets images_path = /opt/gns3/images:

ls -l /opt/gns3/images/QEMU

Drag the device into a project and start it. A QEMU node that boots means the image and template are right.

If it still fails

A stale checksum cache. GNS3 writes a <image>.md5sum file next to each image and trusts it. If you replaced an image but kept its name, delete the .md5sum file next to it and click Refresh.
Registry version 8 is not supported in this version of GNS3 (or a higher number). The appliance uses a newer schema. Per the registry README, schema 8 needs GNS3 2.2.43 or later. Update GNS3, and keep the GUI and server on the same version (version mismatch).
Could not read appliance ... or Invalid appliance file: .... The file is not valid appliance JSON. A common cause is saving a web page instead of the raw .gns3a file. Download it again from the registry's raw file view or the GNS3 marketplace.
The local server option is greyed out. On Windows and macOS, GNS3 disables local QEMU installs unless experimental features are on. Use the GNS3 VM. If neither the VM nor a remote server is set up, you see The GNS3 VM is not available, please configure the GNS3 VM before adding a new appliance.
Docker appliances. They skip the files page. The image is pulled when you first start the node, so the GNS3 VM needs internet access and working DNS (Docker nodes with no internet).

For more errors like these, see the GNS3 troubleshooting guide.

A lighter way to build the lab

If your lab is mostly Linux hosts, services and FRR routers, you may not need appliances at all. Isothrum's editor is a free browser editor that exports a lab of containers as Docker Compose, and any Docker image works, so there are no checksums to match. It can also open your .gns3 project: Docker nodes keep their image and QEMU nodes become VMs. For Cisco images you still bring your own, built with vrnetlab, and IOSv, CSR 1000v and Catalyst 8000v still need KVM.