Installing QIIME 2 using VirtualBox¶
The following steps require at least ~25 GB of free disk space: ~5 GB for the ZIP file, ~5 GB for the unzipped ZIP file contents, and ~15 GB for the installed Virtual Machine (VM). Once you have installed the VM you can free up ~10 GB of space by deleting the ZIP + the unzipped ZIP file contents.
The QIIME 2 VirtualBox image offers a convenient way to get QIIME 2 up and running, and is also the easiest way to get your hands on the experimental preview of QIIME 2 Studio.
1. Install VirtualBox on your computer¶
Please see https://www.virtualbox.org for details on how to install VirtualBox on your computer. Please note, some computers require activating a BIOS setting to enable virtualization — please consult your hardware documentation to determine if you need to do this, and how. After installing VirtualBox, take note of the version of VirtualBox that was installed.
2. Download the QIIME 2 Core VirtualBox Image¶
Please note, this installation document uses some placeholders throughout the following steps.
X.Y.Z represents the version of QIIME 2 (e.g.
build_number represents the build identifier for the VirtualBox image (an internal reference used by the QIIME 2 Developement Team). Please see the VirtualBox Images download link to get the download URL for the latest image. The minimum version of VirtualBox (as determined in Step 1 above) is provided for the latest releases of the VirtualBox image — please ensure you have installed a version of VirtualBox that is equal to or greater than the version of the QIIME 2 VirtualBox image you wish to install.
3. Unzip the file¶
qiimeX_Y_Z-build_number.zip file and open the directory that you chose to unzip to. Please note, some operating systems (e.g. Windows) open a read-only view of the ZIP file, which has not actually been extracted. Please follow the directions for your operating system/unarchiver tool as necessary.
4. Launch VirtualBox¶
Double-click the file named
QIIME 2 Core - X.Y.Z (build_number).ovf.
The file ending with the extension
ovf is a type of VirtualBox “recipe” — it allows the QIIME 2 developers to define a set of reasonable default configuration values, rather than requiring you to manually specify RAM, CPU count, etc. The file ending with the extension
vmdk is the actual virtual machine disk image. If you don’t want to import using the defaults specified in the
ovf you can use the
vmdk file to manually import the VM — see the VirtualBox Docs for details.
You will be presented with an
Appliance Settings import page. We have selected default settings for you that should work for most light workloads. If you are interested in changing the allocations (e.g. memory or CPUs), feel free to adjust these settings. When done, click
Once the import is complete, double-click on the new Virtual Machine entry that matches the
build_number version that you just imported.
5. Launch the virtual machine¶
When prompted, select the user
qiime2, and enter the password
Once logged in you should see a screen like this:
Success! To confirm that everything is working, you can open up a terminal and run the following command:
Note, the list of installed plugins (and their versions) will likely differ depending on the version of the VirtualBox virtual machine that you chose to download and install.
6. Clean up¶
The import process creates a copy of the files from the directory that you unzipped in step 3 above. If you would like to reclaim that disk space, feel free to delete
qiimeX_Y_Z-build_number.zip, and the unzipped folder from that file.