Working with Disk Images

This version of this page is valid for OS X 10.3. If you are on OS X 10.2 or earlier, please visit the 10.2 disk images page instead!

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 compressed using gzip.

Before we begin, 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 file 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 gzipped disk images. 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. Don't be worried if this is gibberish; we will cover this information in much more detail below.

Skip this step: Some, or even all, of the steps described here might be done automatically for you by your browser, or by StuffIt Expander, or possibly by other software installed on your machine. This is intended to make the downloading and unarchiving process easier, but it can be confusing, too; and it certainly makes it harder to write instructions about this topic. A "skip this step" section will be included for each step, to tell you how to recognize the signs that that step have already been done for you.

gzip files (.gz)

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 OS X an easier solution is provided by StuffIt Expander. StuffIt Expander is part of the standard installation of OS X; it can normally be found in the /Applications/Utilities/ folder. If your Finder file-type bindings are correct, you should be able to double-click on any file ending in ".gz" and StuffIt Expander will be launched to uncompress that file. If that doesn't work, you can always drag the gzip file onto StuffIt Expander's icon to directly open the file:

StuffIt Expander's behavior will vary a great deal depending upon its preferences, unfortunately, which makes it a bit hard to describe here. It should uncompress a .gz file to produce an uncompressed version of the file, although even that basic functionality might be modified in the preferences. The original .gz file might be left behind (in case you have some further use for it), or it might be deleted once the uncompressed version of the file has been produced. The uncompressed version might be placed in the same folder as the .gz file was in, or it might be placed in a standard "destination folder" regardless of the location of the .gz file. In essence, though, putting a typical Stick Software product's "Software.dmg.gz" file through StuffIt Expander should produce a "Software.dmg" file somewhere where you can easily find it (perhaps your Desktop or your home directory).

If StuffIt Expander doesn't seem to be doing what you want it to do, double-click on it in the Finder to run it (it typically quits as soon as it finishes the work it was asked to do, so even if you just used it, it probably isn't running any more), bring up its Preferences, and configure things in a sensible manner. We would suggest that, at a minimum, you do the following:

On the "Expanding" preferences page, you check "Expand archives and compressed files".
On the "Destination" preferences page, you select the "Same as Original" radio button.

More suggested settings for StuffIt Expander are given in the section below, "Automating this process".

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, or if that doesn't work, drag it onto StuffIt Expander. A "Software.dmg" file should be produced. If you can't get this to work, you may need to change StuffIt Expander's preferences.

Skip this step: Your browser may automatically decompress .gz files. If so, you should be able to locate a "Software.dmg" file somewhere; that is the result of automatic decompression. If you can find that file, you can proceed directly to the next step.

disk image files (.dmg)

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 a floppy or Zip 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. In OS X 10.3 this is all managed by the Finder. You should be able to double-click on any file ending in ".dmg" and the Finder will then open that file (and thus "mount" the virtual disk). If that doesn't work, then it might be useful to know that internally, an app called DiskImageMounter that is located in /System/Library/CoreServices is used by the Finder to mount disk images; you may drag disk images directly to that app if necessary, or you may want to do Get Info on a .dmg file in the Finder and look at the setting under "Open with:" to ensure that DiskImageMounter is indeed marked by the Finder as being "in charge" of opening disk image files.

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 "Removable media (such as CDs)" 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 Disk Copy application, 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):

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.

What you do: Find the "Software.dmg" file that was produced by your browser or by StuffIt Expander. 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). 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.

Skip this step: Your browser or StuffIt Expander 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. 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.

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 and in StuffIt Expander'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. We will give instructions only for Safari here, because there are so many different web browsers for OS X (Safari, Internet Explorer, OmniWeb, iCab, Opera, Chimera, ...), and many users download files with a separate application anyway, complicating the issue. But it is usually straightforward to set this up; refer to the documentation or technical support for your chosen browser if you can't find the right option in its Preferences.

In Safari, open Safari's Preferences by selecting the "Preferences..." menu item from the "Safari" menu. Find and check the "Open safe files after downloading" checkbox (in the "General" preferences). You might also wish to make sure that the setting for "Save downloaded files to:" is your Desktop, unless you really want them to appear somewhere else. Then configure StuffIt Expander to work with Safari by double-clicking on it in the Finder to run it, bringing up its Preferences, and making the following changes:

On the "Expanding" preferences page, check "Expand archives and compressed files", "Expand encoded files", and "Continue to expand (if possible)". You probably also want to check both of the "Delete after expanding" checkboxes, to cut down on the stray files you have to throw away later.
On the "Destination" preferences page, select the "Same as Original" radio button.
On the "Disk Images" preferences pane, check the "Mount Disk Images" checkbox.

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. StuffIt Expander's documentation may be helpful to you if you have detailed questions about its preferences or its operation; we have tried to give a brief overview of its use, but obviously it is not really within the scope of our responsibilities to fully document and support that product. 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!