When it comes to Mac OS X troubleshooting and maintenance, Repairing permissions may be the most frequently recommended course of action. It’s also easily the most maligned.
The procedure has taken its (rightful) place in the Pantheon of Overused Procedures, next to “zapping the PRAM,” “rebuilding the Desktop,” and “performing a clean install,” with some users acting as if it’s a cure-all for any and every issue anyone might have with a Mac, and something that should be done every day to prevent problems from ever occurring. Conversely, a vocal camp claims that the procedure is worthless —even harmful—and that those who use it regularly are no better than tool-using primates on the evolutionary scale.
The truth about repairing permissions lies somewhere in between. We’re here to help you find it by taking a closer look at repairing permissions—what the function is, what it does, when you should do it, and when you shouldn’t.
What are permissions?
Every file and folder on a Mac OS X hard drive has a set of permissions —settings that determine which user(s) have access to each item, and exactly what that access is. For example, permissions dictate whether or not a particular user can open and edit a particular file. But permissions also determine which items the operating system—or specific parts of it—can access and modify, and which files are accessible by applications. (Brian Tanaka offers more details about various types of permissions in this excerpt from his Take Control of Permissions in Mac OS X ebook .)
What does repairing permissions do?
The Repair Disk Permissions function—the process that actually performs the task of repairing permissions—examines certain files and folders on your Mac’s hard drive to see if their current permissions settings are what Mac OS X expects them to be; if discrepancies are found, the offending permissions are changed to match the expected settings.
(In Mac OS X 10.3 and later, repairing permissions also performs one other, unrelated, task: If the invisible /tmp symbolic link—which is linked to the /private/tmp directory—is missing, the link will be recreated.)
Why is it necessary to repair permissions?
If permissions on particular files are “incorrect”—i.e., not what Mac OS X expects them to be or not what they need to be for your Mac’s normal operation—you can experience problems when the operating system tries to access or modify those files. For example, you may have trouble logging in to your account, printing, launching applications, or even starting up your Mac. Similarly, if an application—from Apple or a third-party developer—needs access to a particular file or folder to function, and the permissions on that item have changed in a way that prevents such access, the application may not function properly (or at all). The Repair Disk Permissions function can fix such problems by ensuring that certain files have the correct permissions.
There’s also a security element here: Many system-level files have permissions set a particular way so that applications or users that shouldn’t be meddling with those files can’t. If the permissions on certain system-level files somehow get changed so that access to those files is no longer restricted, you’ve got the potential for a major security issue. Repairing permissions can resolve such issues by resetting permissions on those files to prevent unauthorized access.
How do I repair permissions?
The Repair Disk Permissions function is part of Apple’s Disk Utility (in /Applications/Utilities). After launching Disk Utility, select the desired disk—generally your startup disk—in the list to the left, then click the First Aid tab. At the bottom of the First Aid panel, click the Repair Disk Permissions button. (You could instead use the Verify Disk Permissions option to preview any potential repairs before performing them, but for most users there’s little benefit from this extra step.)
Permissions can also be repaired via the shell (Terminal) by using the command
sudo diskutil repairPermissions /. However, it’s unlikely that the typical user will ever need to perform the task in this manner. It’s useful if for some reason Disk Utility itself won’t launch, or for repairing permissions on a remote Mac when connected via Remote Login (SSH), but otherwise you’re just as well served using Disk Utility.
How does the Repair Disk Permissions function know what the “correct” permissions are?
When you use Apple’s Installer utility to install software (such as Mac OS X itself or an OS X update), the installation package (the .pkg file you double-click to begin installation, or that Software Update downloads in the background for an automatic installation) generally leaves behind a receipt —a smaller Mac OS X package that includes information about every file installed, including the permissions each file should have. This receipt is placed in /Library/Receipts. When you run the Repair Disk Permissions function, it examines the receipts in the /Library/Receipts directory of the disk being repaired —which means the feature works only on volumes with Mac OS X installed—and compares the information in the receipt with the actual files on your drive. If the Repair Disk Permissions function finds a file with permissions that differ from what a receipt claims they should be, that file’s permissions are reset to their receipt-specified values. (If you’re curious about the information contained in a receipt, the easiest way to view it is to use the utility Pacifist [ ; August 2006 ]; simply drag and drop the appropriate receipt into the Pacifist window and you’ll be presented with a list of all files installed by the similarly-named installation package, along with each file’s original permissions.)
It’s worth noting here that although the function is called “ Repair Disk Permissions,” what is actually happening is that files’ permissions are being reset or restored to a particular state. It’s possible—though not common—for a particular file’s permissions to differ from what a receipt claims they should be without those permissions actually being “broken.”
Are all files affected by Repair Disk Permissions?
No. As you may have inferred from the above description, only those files installed using OS X’s Installer utility and whose installation packages leave behind a proper receipt in /Library/Receipts are affected by the Repair Disk Permissions function. This means that most of the files affected by the Repair Disk Permissions function are system-level files, application files, or system add-ons—not applications installed by drag-and-drop, and not your documents or other user-level files. (See the next section for information about third-party software.)
But beyond that, only certain receipts are referenced, all of them associated with OS-X-related software. This limitation of the Repair Disk Permissions function has been debated around the Web, but you can confirm it yourself with a bit of Terminal savvy: By using the
fs_usagecommand with the appropriate options, you can see exactly which receipt files are accessed when the Repair Disk Permissions function runs. The following is the list of such receipts on my Mac running Mac OS X 10.4:
These receipts are all from installations related to Mac OS X or Apple’s Xcode/Developer Tools. Given that files not listed in the above receipts won’t be affected by the Repair Disk Permissions function, this means that repairing permissions is mainly a tool for fixing permissions-related problems with OS-level Apple software .
Why does the Repair Disk Permissions function look at only these receipts?
These receipts are explicitly listed within the code of DiskManagementTool , the component of OS X that actually performs the task of repairing permissions. You can verify this by using the following command in Terminal:
strings /System/Library/PrivateFrameworks/DiskManagement.framework/Versions/A/Resources/DiskManagementTool | grep Receipts
(I’ve placed the command in a scrolling box so it wouldn’t be broken incorrectly. The output from that command is a list of all receipts included in the code of DiskManagementTool.)
Does repairing permissions affect third-party application files?
Apple’s description of the Repair Disk Permissions function seems to imply that any software, including third-party software, installed using Installer and accompanied by a receipt in /Library/Receipts is affected by repairing permissions. However, we know from the previous answer that this isn’t the case. The only third-party software affected by repairing permissions is software included with Mac OS X and installed by the Mac OS X Installer; for example, the Flash browser plug-in (/Library/Internet Plug-Ins/flashplayer.xpt) and—in older versions of Mac OS X—Microsoft’s Internet Explorer browser.
It’s easy to verify that third-party software isn’t affected. For example, I changed the permissions on the file NuFile.plugin , a third-party contextual menu plugin, from their original values. Since NuFile.plugin was installed using OS X’s Installer utility and a receipt, NuFileInstaller1-8.pkg , is present in /Library/Receipts, you might expect that the Repair Disk Permissions function would restore NuFile.plugin’s permissions to their original values. It doesn’t. I performed a similar test on the TiVoDesktop System Preferences pane with similar results.
Although some might argue that restricting the Repair Disk Permissions function to Apple-installed software is a limitation, it’s also good security. If third-party receipts were used as references when repairing permissions, a piece of malware could leave behind a receipt designed to maliciously change permissions on system-level files—for example, to assign more-accessible permissions on normally secure files and directories. This could be a major security risk.
That said, keep in mind that many third-party software products rely on components of Mac OS X. So although repairing permissions may not directly affect third-party software, if a permissions-related glitch with OS X’s own files is causing a problem with third-party software, the Repair Disk Permissions function could affect that software by fixing the underlying cause of the problem.
Can I get rid of receipts in the /Library/Receipts folder?
If you remove receipts from /Library/Receipts, the Repair Disk Permissions function will no longer affect files referenced in those receipts; if a permissions issue with one of those files is causing a problem, you won’t be able to fix the problem by repairing permissions. But beyond that, some receipts are necessary for the Repair Disk Permissions function to work at all, as described below. In addition, receipts are often used by Mac OS X’s Software Update and third-party software installers to determine whether or not you’ve already got a particular piece of software installed.
On today’s larger hard drives, even a jam-packed Receipts folder is likely to be a few hundred MB or less in size; it’s best to simply leave the contents of this folder alone.
Can I move the files affected by the Repair Disk Permissions function?
File locations are hard-coded in receipts; if you move files listed in a receipt, those files won’t be checked when you repair permissions. This is a good reason not to move Apple-installed software.
I’ve read that before repairing permissions, you need to boot from the volume being repaired because Repair Disk Permissions uses the /Library/Receipts folder on the boot volume to determine correct permissions. Is this true?
This was true in early versions of Mac OS X. In fact, it used to be that if a permissions issue prevented you from booting off your normal startup volume, you needed to repair permissions while booted from the Mac OS X Install disc. Then, once you were able to successfully boot from your normal volume, you used the procedure again to ensure the “correct” receipts were used. However, in all recent versions of OS X, Disk Utility uses the /Library/Receipts folder on the volume actually being repaired, boot or not.
Whenever I try to repair permissions, I get an error that states…
Let me guess: First Aid failed: Disk Utility stopped repairing permissions on ’[volume name]’ because the following error was encountered: No valid packages or Error: No valid packages (-9997). As explained above, the Repair Disk Permissions function uses receipts located in /Library/Receipts to determine what the correct system-level file permissions should be. At a minimum, the procedure requires that a receipt named BaseSystem.pkg —which outlines the default permissions for core Mac-OS-related files and folders—be present. If this receipt is missing, the procedure will fail with one or both of the above errors.
If you find yourself in this position and the BaseSystem.pkg package is no longer present anywhere on your hard drive—so you can’t simply move it back to the Receipts folder—Apple recommends copying it from another computer running the same version of Mac OS X as your own. If that’s not an option, either, then Apple recommends reinstalling Mac OS X. (If your Mac OS X Install disc is for the same version of Mac OS X as is running on your Mac—for example, 10.4.2—you can do a standard install, which simply replaces existing system files with newer versions. However, if your Install disc would install an older version of Mac OS X—for example, 10.4.0 when your Mac is currently running 10.4.6—you need to perform an Archive and Install installation and then update to the latest version of OS X via Software Update.)
Why do I see so many “special permissions” errors when I repair permissions?
The short answer is “Because you haven’t yet updated to Mac OS X 10.4.6 or later.” The long answer is that Apple has at times decided, for various reasons, that certain newly-installed or recently-updated files should actually have different permissions than those of an earlier version. For example, say a file installed with Mac OS X 10.4.0 had particular permissions, outlined in the BaseSystem.pkg receipt, but Apple changed the permissions for that file in a later update to Mac OS X. In such a scenario, there would be a discrepancy between the desired permissions on the file and what the older receipt claims those permissions should be; the Repair Disk Permissions function would try to “fix” the permissions on that file to match the original BaseSystem.pkg receipt, even though those permissions are now “incorrect.”
To avoid such erroneous repairs, recent Apple updates include a file called HintFile.plist , installed in /System/Library/PrivateFrameworks/DiskManagement.framework/Versions/A/Resources, that lists any file permissions that should differ from what’s listed in receipts. Essentially, this file tells the Repair Disk Permissions function, “Ignore what those receipts say about file-such-and-such; the permissions on that file should really be…”
In older versions of Mac OS X, you would see this conversation unfold on your screen in the form of “special permissions” errors in Disk Utility. However, as part of the Mac OS X 10.4.6 Update, Apple modified the Repair Disk Permissions function so that it no longer presents these messages in the Disk Utility window. Nothing has changed in terms of what’s happening behind the scenes; you just no longer have to read the narrative. If you’ve got an older version (pre-10.4.6) of Mac OS X installed, you can simply ignore any message that includes the phrase “We are using special permissions.”
What causes permissions to change?
If you browse the Web, you’ll see many claims that “permissions don’t change on their own.” And to a large extent, that’s true—for permissions to change, something, or someone, must change them. But there are a number of ways permissions can be changed. Here are a few examples:
This isn’t an exhaustive list, but it does show that although permissions don’t magically change, there are enough ways for them to be changed that you should consider a permissions issue as a possible cause if you experience problems with your Mac. (Apple provides a similar list of possible causes of permissions issues in this Knowledge Base article.)
Is repairing permissions “useless,” as I’ve read on the Web?
Repairing permissions is not going to fix all of your Mac’s problems, or even most of them. Many of the problems for which I see the procedure recommended as a possible solution—for example, slow Internet performance, problems with user-level application preferences, or even permissions issues that prevent you from deleting documents—are unlikely to be solved by repairing permissions. However, the procedure will fix those problems relating to incorrect system-related permissions. How common such problems are is a subject of fairly intense debate, but what isn’t debatable is that such problems do in fact occur, and the Repair Disk Permissions function is quick enough and easy enough to use that repairing permissions is one of the first procedures Apple’s tech support representatives will ask you to do (and most Geniuses in Apple Stores will do) to your Mac when you’re experiencing a problem.
A similar but not quite as extreme argument I hear is that you shouldn’t use the Repair Disk Permissions function as a troubleshooting tool unless you’re sure you have a permissions-related problem. This sounds like logical advice, and advice that makes sense for any troubleshooting procedure—in an ideal world, you’d use only the appropriate troubleshooting tool for the job. But the trouble with this argument is that most Mac OS X users don’t know how to determine if a problem is truly caused by a permissions issue. And even among experienced troubleshooters, many procedures are used as much to eliminate possible causes of problems as they are to actively fix problems. Repairing permissions is useful in this context because it’s a quick and easy way to eliminate a system-level permissions issue as the cause of a problem.
If repairing permissions is useful in general, why doesn’t Apple recommend it as routine maintenance?
Apple does, quite explicitly:
It’s a good idea to repair disk permissions as a regular maintenance task after upgrading or installing new software.
That’s taken from Mac Help—in both Panther and Tiger—right on your Mac; an online version can be read here. Similar statements can be found in other Support articles. Now, to be fair, I suspect that Apple makes such recommendations not because it’s usually necessary, but rather because, as mentioned in the previous item, if a permissions-related problem does occur, repairing permissions is a quick and easy way to fix it. The fact that Apple specifically recommends the procedure after installing software seems to confirm my suspicions that bad installers are the most common cause of permissions glitches.
Should I repair permissions as routine maintenance?
Some people claim that, just like periodically running a disk repair utility, repairing permissions regularly will help your Mac run more smoothly. But there’s a key difference here: Minor drive or directory damage—the kind that can be caught early and easily fixed—can affect the way files and folders are written to and located on your hard drive. That means regular checks of your drive can prevent more serious problems, including data loss, down the road.
However, that’s rarely the case with incorrect permissions. Even if a permissions issue does cause problems, it shouldn’t lead to more serious issues; things specifically affected by these “bad” permissions may not work properly, but one incorrect permission doesn’t lead to other incorrect permissions, and a permissions issue will rarely lead to data loss. In other words, the benefits of being “proactive” about permissions repairs are minor for most users; you’ll be served just as well by repairing permissions after you experience a problem. (This is especially true in Mac OS X 10.3 and later, as permissions-related problems occur much less frequently now than with earlier versions of Mac OS X.)
That said, if it makes you feel safer to perform the task regularly, it’s highly unlikely to hurt anything (see below ). And if you’re in a higher-risk group—for example, someone who installs lots of software—repairing permissions as “maintenance” or after a software update, as Apple recommends, may avoid a bit of inconvenience by fixing incorrect permissions before they manifest in noticeable symptoms.
Do I need to repair permissions before installing an update to Mac OS X?
In a word, no. When you install a Mac OS X update, you’re required to authenticate—provide an admin-level username and password—in order for the installation to proceed. When you authenticate, you’re allowing the installer to run with the equivalent of root access. What this means is that the installer is not constrained by Mac OS X’s permissions system—it ignores the normal restrictions of file and folder permissions. This is necessary for Installer to be able to update Mac OS X, but, more important for the current discussion, it also means that “incorrect” permissions shouldn’t cause problems with the installation.
The only real benefit to repairing permissions before a Mac OS X update is that if you do so, then immediately install the update, and then repair permissions again immediately afterwards, you can be pretty confident that any permissions issues that are found are a result of the update. But at that point you’ve also fixed the problem(s), so the pre-install “repair” provided you with little more than academic knowledge.
Do I need to repair permissions after installing an update to Mac OS X?
If you experience new problems immediately after installation, repairing permissions is the first step you should take, but there’s no real need to do so as a matter of habit. As explained above, Mac OS X’s Installer installs files with the necessary permissions and then leaves a receipt or receipts that outline those permissions. Unless a problem occurs with the installation, the permissions outlined in the receipt(s) will match the permissions on the actual files that have been installed; in other words, no repairs will be necessary.
However, that’s not to say that permissions problems can’t happen during an installation. I’ve seen plenty of controlled, reliable reports of Macs that have been “permissions perfect” before an installation but have experienced permissions-related problems afterwards. Even Apple notes that “Permission problems sometimes happen after you update your system or install new software.” (I personally had a problem with a particular update to Panther [Mac OS X 10.3] where none of my non-boot drives would mount. It turned out that during the update installation, the permissions on the invisible /Volumes directory had been changed. A quick Repair Disk Permissions, and I was good to go.) But these are the exceptions, not the rule—the vast majority of users will be fine repairing permissions only after they experience a problem.
But as I mentioned with respect to routine maintenance, if it helps you sleep better at night to repair permissions after each OS X update, don’t let me stop you. And it’s likely more efficacious to do so after software updates or installations than on a regular (e.g., weekly) schedule.
Given that Apple recommends repairing permissions after updating Mac OS X, why doesn’t Apple’s Installer do it automatically?
I asked Apple that very question; the company declined to comment. For what it’s worth, repairing permissions isn’t the only procedure to fall into this category; there are many other useful procedures and processes Mac OS X doesn’t automatically perform. For example, it’s a good idea to periodically check your hard drive for problems, and Apple recommends doing so; although Mac OS X could easily perform this task on a weekly basis, it doesn’t.
Can repairing permissions hurt anything?
Critics of frequent permissions repairs claim that the procedure can actually do more harm than good by resetting permissions that have been changed from their defaults—presumably for good reason—by the user, an application, or an installer. Although this is a valid argument in theory, in reality it’s not something most users should worry about. For starters, remember that the Repair Disk Permissions function doesn’t touch user-level files, so your data is safe. The procedure also doesn’t touch third-party software. So you’re left with only OS X’s own system-level files, and if Apple makes such changes, it already has two mechanisms—receipt files and the HintFile.plist file—for ensuring that the Repair Disk Permissions function sets permissions properly. (There have been rare examples of Mac OS X updates working fine until the user repaired permissions; however, these issues were due to errors in Apple’s installer scripts and receipts—not the Repair Disk Permissions function—that were fixed in revised versions of the updates.)
What about more advanced users who intentionally change permissions on system-level files—clearly an unsupported procedure—in order to modify the system in some way? It’s reasonable to expect that people savvy enough to perform such tweaks should also be savvy enough to (a) understand the possible consequences; (b) keep track of such changes and remember to re-implement them after repairing permissions; and (c) avoid repairing permissions unless absolutely necessary. Similarly, if a piece of software changes permissions in a way that could be reset by repairing permissions, the developer of the software should account for that fact—either in software or by clearly noting the issue in the software’s documentation. This is especially true of software installers likely to be used by people who aren’t necessarily experts—it’s the developer’s responsibility to prevent a common procedure recommended by Apple from breaking the software. The fact that these advanced users and software products exist is hardly a convincing argument against your typical Mac user repairing permissions, even frequently.
And remember to keep this risk in perspective: A very small minority of users tweaking system-level Apple components that also happen to be affected by the Repair Disk Permissions function. I know of few people who tweak their Macs more, and install more software, than I do, and I’ve never fallen victim to such a scenario. In fact, the last time even I heard of such a situation in the real world was back in Jaguar (Mac OS X 10.2) when a particular procedure for customizing OS X’s built-in mail server was affected by repairing permissions.
Bottom line: It’s extremely unlikely that repairing permissions will adversely affect your Mac or its software; the chances of the Repair Disk Permissions function doing harm are much, much lower than the chances of it helping if you’re experiencing a problem. For the vast majority of Mac users, it’s a harmless procedure, and the small number of people who might be adversely affected should already be aware of such risks. If you’re concerned, use Repair Disk Permissions’ Verify mode—which shows which permissions would be reset but doesn’t actually make any changes—first; if everything looks good, then use Repair mode.
What if a permissions problem is preventing my Mac from starting up?
It’s rare that a permissions-related issue will actually prevent your Mac from starting up; however, it does happen. If you find yourself in a situation where you can’t start up your Mac, one of the easiest troubleshooting procedures involves starting up from the Install disc (CD or DVD) that came with your Mac and then using Disk Utility—via the Utilities menu that appears when booted from the disc—to check your hard drive for damage. But you can also use the Repair Disk Permissions function while booted from the disc to ensure that system-level file permissions are correct. (Note that Apple has a number of articles dealing with other causes of startup problems; there’s a good chance your troubles have nothing to do with permissions.)
A similar solution can be found in the free AppleJack ( ; August 2006 ), a third-party maintenance and troubleshooting utility. Like Disk Utility, AppleJack can repair permissions on your startup drive, but because it runs in single-user mode at startup, it can often fix permissions-related issues that are preventing Mac OS X from starting up properly, and it doesn’t require you to have your OS X Install disc on hand. Unfortunately, AppleJack isn’t yet compatible with Intel-based Macs.
(Given that you can access a shell at startup via single-user mode, and that I previously showed you the command for repairing permissions via Terminal, you might think that you could repair permissions in single-user mode using that command. Unfortunately, for various reasons, this doesn’t work without manually starting a number of other services first, a procedure too complicated to get into here. I recommend using either your Install disc or AppleJack.)
What about Mac OS X Server?
For the most part, the information in this article applies equally well to Mac OS X Server. However, since a server administrator is more likely to purposely change the permissions on system-level files than a typical user—Apple has specifically recommended a few such changes over the years—be aware that if you make such changes, using the Repair Disk Permissions function may revert them.
I’m curious about other coverage of this topic. Where can I go?
Here are links to a number of other articles around the Web that discuss repairing permissions:
UPDATE 8/26/06 : This story was updated on 8/27/2006 to add information about where the list of receipts is located and how to repair permissions via Terminal. Information about Mac OS X Server and a list of links to other articles on the topic of repairing permissions were also added.
DAN FRAKES is a Macworld senior editor.
Author: Dan Frakes
Dan is former Macworld senior editor. You can find him on the web at danfrakes.com.