Working with Disk Images

Stick Software products are distributed using a packaging method called a disk image. Disk images are easy to use once you know how, but many users initially find them confusing. The purpose of this page is to help users who are unfamiliar with disk images get started. Before we even get into that, however, we will touch briefly on gzip files, since Stick Software disk images are sometimes compressed using gzip.

Before we begin with that, however: if you have your Finder preferences set to hide extensions, you should change that. You are just hiding useful information from yourself, and once you turn extensions on, you will soon become so accustomed to them that you will wonder how you ever managed without them. Just switch to the Finder, select "Preferences" from the Finder menu, select the "Advanced" settings, and check the checkbox labelled "Show all filename extensions". Now you will be able to see the ".gz" and ".dmg" file extensions on the ends of the names of files on your disks (as well as many other kinds of file extensions). Without these extensions, it is more difficult to determine what type the Finder considers different files to be, and the rest of this page will make a lot less sense.

Stick Software products are distributed as disk images, sometimes compressed with gzip. This means that the software is first packaged into a disk image, so it ends up with a filename like "Software.dmg", and then it is gzipped, giving it a filename like "Software.dmg.gz" (for example; in practice, it might be "Measles.dmg.gz" or "Eyeballs.dmg.gz"). To get to the software, you first undo the gzipping process, bringing you back to "Software.dmg", and then you mount the disk image (making a virtual disk called "Software", in this example) to get at the software within. Here are the icons associated with each step of this process for a download of Measles, our bouncy CPU monitor and desktop companion:

On the left is the gzipped disk image, in the center is the disk image file itself, and on the right is the virtual disk mounted when the disk image file is opened (note the exact icons depend on the version of OS X you're running, but they ought to resemble these enough to be recognizable). Don't be worried if this is gibberish; we will cover this information in much more detail below. [Note that the screenshots shown on this page are ancient, from OS X 10.3 probably; but this process has not really changed appreciably, so you should be able to follow along.]

gzip files (.gz)

Skip this step: Your browser may automatically decompress .gz files, or your download might have been an uncompressed disk image (i.e. "Software.dmg" instead of "Software.dmg.gz"). If so, you should be able to locate a "Software.dmg" file somewhere, and that is your download. If you can find that file, you can proceed directly to the next step.

A gzip file is a compressed version of an ordinary file. A gzip file can be identified by its ".gz" extension (meaning that its full filename ends with the suffix ".gz"). These files are called "gzip" files because they are created by a Unix-based compression utility called gzip. They can be uncompressed using another utility, gunzip, but in recent versions of OS X the Finder can also uncompress gzip files. Double-clicking a typical Stick Software product's "Software.dmg.gz" file should produce a "Software.dmg" file in the same folder.

What you do: Find the "Software.dmg.gz" file that you downloaded (wherever your browser is configured to put files that you download). Double-click it to uncompress it. A "Software.dmg" file should be produced.

disk image files (.dmg)

Skip this step: Your browser may automatically open (i.e. mount) .dmg files. If so, you should be able to locate the corresponding virtual disk on your Desktop; that is the result of the automatic mounting. A Finder window might even open automatically showing you the contents of the virtual disk. If you can find that disk, then you can just copy what you want and eject the virtual disk, skipping the initial step of mounting the disk. You will need to follow the rest of the instructions below, however.

Disk images are a way of packaging several files together for convenience, so that they can be downloaded and copied as a single file. A disk image file can be identified by its ".dmg" extension (meaning that its full filename ends with the suffix ".dmg"). These files are called "disk image" files because when they are opened to access their contents, your computer acts as if an actual physical removable disk (such as USB thumb drive or – for you old-timers – a floppy disk) had been inserted. A disk icon representing this "virtual disk" will appear in the Finder, and when you are finished with the virtual disk, you "eject" it just as if it were an actual physical disk. Ejecting the virtual disk simply closes the disk image file, which makes the virtual disk disappear from the Finder. Opening a disk image is sometimes referred to as "mounting" the disk, and ejecting the disk is sometimes referred to as "unmounting" it. So if you double-click on any file ending in ".dmg", the Finder will then open that file (and thus "mount" the virtual disk).

The behavior of the Finder will vary somewhat depending upon your preferences; the "virtual disk" mounted by the Finder may or may not appear on your Desktop, and may or may not be visible in the "Sidebar" of icons on the left of every Finder window. To configure where virtual disks appear for you, switch to the Finder, select "Preferences" from the Finder menu, and check the appropriate checkboxes: the checkbox that governs whether virtual disks appear on the desktop is the "CDs, DVDs and iPods" checkbox in the Finder's "General" preferences, while the checkbox that governs whether virtual disks appear in the Sidebar is the "CDs, DVDs and iPods" checkbox in the Finder's "Sidebar" preferences. (Yes, Apple could be a bit more clear about this.) To minimize confusion and maximize available information, we recommend that users check both of these checkboxes.

If your Finder preferences are set up as recommended, opening a disk image file named "Software.dmg" should cause a new "virtual disk" to appear on your Desktop with a name like "Software". Sometimes a window will be opened automatically to show the contents of this disk; sometimes you may need to double-click on the disk named "Software" to open a window showing what is inside it:

This virtual disk is really a sort of a view into the inside of the Software.dmg file. While the virtual disk is mounted, the Software.dmg file is busy being used by the Finder, and it cannot be thrown out (the trash will refuse to empty). When you are finished with the virtual disk, you can select it and eject it (by dragging it to the Trash, or by selecting the "Eject" menu item in the Finder, or clicking the Eject icon for the virtual disk in a Finder window's sidebar):

After the virtual disk has been ejected, the Software.dmg file will no longer be busy, and you will be able to throw it away successfully. Typically, you won't have the virtual disk mounted for very long. You will immediately copy whatever you want from the virtual disk onto your computer's local hard drive, and once the copy has completed, you will eject the virtual disk and then throw away the .dmg file. Sometimes users accidentally use the software directly off of the disk image, instead of copying it to their local disk first. This leads to great confusion, as the virtual disk will then be unable to be ejected, and the .dmg file will not be allowed to be thrown out. If this happens to you, quit whatever software you may be running off of the disk image, remove that software from your Dock if you added it there, close any files that you have open from the virtual disk (such as "Read Me" files), and then start over by copying the files you want to your local hard drive first. If you get really tangled up and can't understand what is happening, logging out and back in may help clean things up since it will quit all apps and close all disk images.

What you do: Find the "Software.dmg" file that you downloaded or produced by decompressing a "Software.dmg.gz" file. Double-click it. A virtual disk named "Software" (or whatever the product name is) should appear on your Desktop (if not, you may need to change the Finder's preferences). Double-click it to open a Finder window showing its contents. Copy what you want from the virtual disk onto your local hard drive. Select the virtual disk, eject it, and then you should be able to throw away the .dmg file.

Where to copy things

In the previous discussion, we glossed over the question of where exactly you are supposed to copy things to, when you copy them off of the virtual disk. We just said to copy them "onto your local hard drive". Where you want to copy a given software product depends upon the type of software it is (an application, a screensaver, a preferences panel, etc.) Stick Software products should always have a "Read Me" file on their virtual disk that tells you where that product should be copied in order to correctly install it. Open that Read Me file and follow its instructions, and you should be set up properly.

Just as a general illustration of the idea, here is an example of installing Measles by dragging it from the virtual disk "Measles" (the upper left window) into the /Applications folder of the local hard disk (the lower right window):

The application being dragged is visible in the lower right; the green "plus" symbol next to it indicates that it will be copied from the virtual disk when the mouse button is released.

Remember, though; not all kinds of software should be installed in /Applications. The "Read Me" file for the product you have downloaded should give you specific installation instructions.

Automating this process

Depending upon your browser, you may be able to set things up (in your browser's preferences) so that when a .dmg.gz file is downloaded, it will be uncompressed and then mounted automatically. All you will need to do is copy the software off the virtual disk, and then eject the disk and throw away up the download files. However, setting this up is browser-specific, and changes from version to version, too, so you'll need to consult your browser's documentation if you want to get into that.

Downloading issues

Occasionally, we get email from users who have trouble downloading our .dmg.gz archives. They click on the appropriate link in their browser, and rather than beginning a download of the file to their local disk, the contents of file begin spewing out into their browser window as if the archive were a text file. Obviously this is less than useful.

There are a number of possible causes for this: the way your browser handles particular types of files may be misconfigured, the server serving the file may incorrectly inform your browser of the type of the archive file, or your browser may simply be buggy. Regardless, there is an easy solution: use your browser's "context menu" to tell it to download the link to disk. To do this, just hold down the <control> key and click on the link for the archive. A menu should appear underneath your mouse cursor, containing several choices. One of the choices should be something like "Download Link to Disk" (or perhaps "Download Link...", "Save Link to Desktop", or a variation on this theme). Select that choice, and the archive file should be download correctly. You may be asked to choose a filename and location for the downloaded file, or it may be placed in a standard location configured in your browser's preferences.

Further questions

We've tried to be as thorough as we could here; however, it is a surprisingly complicated topic, and there may be questions we have left unanswered. Please feel free to contact us with any questions you have, comments on this page, or other issues, by sending email to our support email address. Happy downloading!