Mac OS X: Troubleshooting installation and software updates

Resolution

Before Installing

Read "Before You Install" information

Read the "Before You Install" or "Read Me" type document if one is available for the software you are installing. This may list the system requirements and any known issues. The Knowledge Base contains many documents about software updates. Try searching on the name of your software update while using the Knowledge Base keyword "kbdload".

Have the administrator username and password available

You must have an administrator username and password to install software updates.

Enough disk space

Make sure you have enough disk space. Even small application or system updates may require a few hundred megabytes of space to complete the optimization phase of the installation. Mac OS X itself may require 3.0 GB of free space, or more, depending on the version and installation options you select.

Use Disk Utility if installing to resolve an issue

Use Disk Utility to check the Mac OS X volume before installing, if you are installing or reinstalling to correct an issue. Tip: Mac OS X 10.3 and 10.4 and later check the target disk automatically during installation.

Do not use the computer while installing an update

Though not required for most updates, you may want to avoid using the computer while installing updates. You may even want to restart the computer immediately before installing an update. Shut down the Classic environment to maximize the amount of memory available for the installation.

Choosing disk format (full installation / erase installation only)

Mac OS X can be installed on volumes of different formats. These disk formats have different features and characteristics. If you also plan to use Mac OS 9 or don't have a preference, you should choose Mac OS Extended (HFS Plus) format instead of UNIX File System (UFS). Journaling is usually also desirable. More information is available in "Mac OS X: Choosing UFS or Mac OS Extended (HFS Plus) Formatting".

Is it an installation issue or a startup issue?

Some installations restart the computer automatically, which you may not notice if you start an installation and then leave your computer. If you do not see the installer on your screen when you return, and the computer does not start up successfully, treat this as a startup issue. See "Mac OS X: Troubleshooting a Startup Issue".

Portable computers: Set Energy Saver preference Optimize Energy Saver Settings to Highest Performance.

If you are installing on a portable computer, make sure that the computer is connected to the AC power while you are downloading and installing the update. During the update process, do not put your computer to sleep, and do not let it go to sleep.

Mac OS X 10.4 Tip: If installing Mac OS X 10.4 while started from your Install disc, you'll be alerted if AC power is not connected to your portable Mac.

Verifying the installation

Check the build number

If you are unsure that the installation was completed, check the software build number. If the build number of Mac OS X or other software has changed to reflect the new update, then all of the software has been installed.

Check logs (advanced technique)

If an alert box appears with a message that says: "There was an error while installing," check the logs for the specific issue.

• Installer log. When started up from an installation CD-ROM disc or installing a package file from a disk image, choose Show Log from the File menu (or Window menu with Mac OS X 10.4). If the information in the log window is not helpful, select the Show More Detail option. If you are going to call Apple, save the log file or write down the last few lines.
  These are the locations and names of the log files:
  • Mac OS X 10.2.8 or earlier: "Mac OS X Update" or "Mac OS X Log" in /Library/Receipts/ folder
  • Mac OS X 10.3 or later: "install.log" in /var/log folder
• Software Update log. This log is available from the Software Update pane of System Preferences. This log just lists which update had an issue. It does not give you detailed information about the issue.
• Console log. Use the Console utility to check the logs used by Mac OS X, which are "console.log" and "system.log". Look for messages containing the word "Install" or messages that appeared during the time of the installation.

Troubleshooting an unsuccessful installation

If installing from CD-ROM

If you have trouble using an installation CD-ROM, first see "Troubleshooting Mac OS X installation from CD or DVD".

Restart the computer and try again

Restart the computer and try installing the update again. Some installation issues are not reproducible, you may succeed the second time.

Use Disk Utility

Start up from the Mac OS X Install CD. Use the Disk Utility application to verify the disk with Repair Disk (not permissions) of the volume you are trying to install onto. After verification or any necessary repair, try the installation again.

Disconnect devices not used during installation and remove non-Apple RAM

If the issue persists, disconnect any other drives you may have connected to your computer and retry your installation. Other devices could potentially affect your installation. Disconnect or remove anything that did not come with your computer. If removing all non-Apple memory would leave you with insufficient memory to install Mac OS X, then remove everything but the memory. If your issue persists, you may have an issue with your non-Apple memory.

Try a different software update source or CD if possible

Software Updates for Mac OS X and Apple applications for Mac OS X are often available three different ways:

• Software Update preferences.
• Your iDisk (if you use .Mac)
• Standalone installer from Apple Downloads.

Try getting the software from a different source, or download it again.

Try a new administrator account

Creating a new administrator account and using it to install the update may lead to success. If you don't know how to do this, see the "If the issue occurs in Mac OS X or in various applications" section of this document: Mac OS X: How to troubleshoot a software issue.
If this works, log out and back in as your normal user. You may delete the new administrator user, if desired.

Installation fails during "optimization"

If the installation fails during "optimization," all of the software was installed. There is no risk of an "incomplete installation." The optimization phase of an installation only affects performance and not stability or features. You may force optimization to be repeated by reinstalling the software. If you were using the Software Update pane of System Preferences on the first attempt, you will need to download the standalone installer of the same software from Apple Downloads in order to reinstall the software.

Consider the RAM

For installations from a disc, marginal-quality memory can contribute to installation issues; issues that may not otherwise be apparent in day-to-day computer tasks. Remove some of the RAM from your computer, but not so much that you are below the minimum required to install the software).

Erase install

Erase installs often succeed where installations without erasing fail. You should make sure you have a working backup of your important data before erasing the volume. Due to the extreme nature of this solution, you may wish to try all other steps first.

Warning: This procedure deletes all data on the targeted volume. Back up any data you wish to keep before performing this step.

About "Downgrade" installations

You should not reinstall an earlier version of the same software over a later version. These "downgrade" installs may seem to work, but Apple does not test nor recommend downgrade installations in most cases. Some installers prevent downgrade installations. If you need to reinstall an earlier version of Mac OS X, erase your disk first or choose the erase option in the Mac OS X Installer. Be sure to reinstall any software updates after reinstalling the operating system.