The macOS installer is quick and easy to use, but you can find out more info on what happens during installations by checking its built-in logs. Here’s how to look at them.
macOS installer files are called Packages and usually have a file extension of .pkg. When you open a .pkg to install software on your Mac, Apple’s installer app performs a complex series of steps to verify and install the software.
Most .pkg files are built to contain a series of standard steps in which the package is first verified, then payloads are decompressed and copied to the target drive.
Lastly, post-install scripts are run to check the installation, set file permissions, and do any post-install cleanup.
From the GUI, this all looks like a simple and quick process. But, behind the scenes, a lot is going on.
Luckily, the installer keeps a detailed record of what happens during installation. It’s easy to view this log, save it to a text file or print it.
Installer is a generic app which runs .pkg files
Most .pkg files don’t actually contain an installer app – instead they get read and run by macOS’s installer app (Installer.app) which lives on your Startup Disk at /System/Library/Core Services. The current macOS Sequoia 15.3 installer app version is 6.2.
When you double-click a .pkg file in the Finder, macOS launches the installer app and then passes the file path of the .pkg to it so it can be read.
To get a list of all .pkg files on your Mac, press Command-F on your keyboard, then set the search terms to “Kind is Other”, then enter “Installer” in the search field to the right.
.pkg files are Bundles, special folders in macOS – just like most apps are. It’s also possible for .pkg bundles to contain other packages.
This is also true of custom installers built by developers, which don’t get run by Installer.app.
Four packages bundled inside Apple’s Xcode app.
Starting in Mac OS X 10.5 Leopard, Apple provided developers the ability to create flat installer package files. They are single encoded files rather than bundle folders, but which still have the .pkg filename extensions and get run by Installer.app.
Flat file packages prevent users from opening the .pkg bundles and looking inside with the Finder’s Show Package Contents contextual menu item, or with the Terminal app.
Either way, when opened, Installer.app runs the .pkg and executes what it finds inside.
If a .pkg is not a flat file package, you can Control-click on it in the Finder and then select the Show Package Contents item from the contextual menu to open the .pkg bundle and see what’s inside it.
Don’t change anything inside a .pkg because many .pkgs contain digital singing information, which has to match the .pkg’s contents.
Viewing installer logs after installation
A typical .pkg installation will open a single standard Installer.app window displaying installation progress, including steps and messages during installation. When installation completes or fails, Installer will display the results and a message such as “The Installation was successful”.
At this point, the user would normally click the Close button in the installer window.
Installer.app with a completed installation.
If instead of clicking the Close button, the user selects the Window menu, a menu item titled Installer Log (Command-L) is available. Selecting Installer Log prompts Installer.app to open a log window that displays full text of what happened during installation.
The default display in the log is to show Show Errors Only. But if you click the Show Errors Only menu item in the toolbar at the top of the window, you can also select either Show Errors and Progress, or Show All Logs.
Select “Show All Logs” to see eveything that happened during installation.
Selecting Show All Logs changes the log window’s text to display the full, detailed steps the installer ran during installation – and any errors. There’s also a Search field at the top of the log window to search the log text, and a Save and Print button.
Save is particularly useful if you’re doing multiple installs from different .pkg files and want to keep records of all the installations.
Once you’ve saved or printed each log, you can safely Quit the installer.
The installer log shows lots of useful information including:
- Time and date of installation
- Mac hardware and software configuration
- User name
- Install target path
- Install components
- Errors or warnings
- More
Installer receipts
After each install, macOS appends a short record to a file named “InstallHistory.plist” located on your Startup Disk at /Library/Receipts. This is a standard XML file in Property List (.plist) format which you can read with any text editor, or with Apple’s Xcode developer app.
Each item in the InstallHistory.plist file is an XML dictionary containing a small amount of info about the installation performed – one sub-item of which is named “packageIdentifiers”. This array contains a list of all the bundle IDs of the installer(s) which were run.
Think of a .plist dictionary as a nested set of XML data with a name (key), and a group of data items (such as strings, arrays, dates, numbers, or other dictionaries).
A bundle ID is simply text that uniquely identifies an app or .pkg to macOS. For example “com.apple.installer” is the bundle ID of the macOS installer app itself. Each bundle ID must be unique in order to avoid app and .pkg conflicts.
install.log
If you want to view the system-wide log file (install.log) on macOS, it lives on your Startup Disk at /private/var/log. Beware though: unless you’ve just recently done a clean install of macOS the file can be huge – as in thousands or even tens of thousands of pages.
You will need to show invisible files in the Finder in order to view /private/var/log. You can view any macOS .log file using any plain text editor including TextEdit provided by Apple.
Most macOS log files live in this folder or in /Library/Logs in the user folder.
You can also view the install.log file by running macOS’s Console app in the /Applications/Utilities folder on your Startup Disk. Console shows you all system logs in one centralized place.
To view install.log in Console, simply select Log Reports in the sidebar, then double-click install.log in the file pane on the right. There are also options for clearing logs, and revealing where they live on your Startup Disk.
pkgutil
macOS also includes a command-line Terminal app called pkgutil, which is a general purpose .pkg utility. To see options and instructions for use, in Terminal type:
man pkgutil and press Return on your keyboard. To exit the manual system, press Control-Z or q. You can also type pkgutil -h in Terminal to get a list of pkgutil commands.
pkgutil has some cool options which let you view info about .pkgs on your Mac. A few of the more interesting options are:
- — pkgs (display all installed package IDs on a given volume)
- — files (display files installed by the specified package)
- — pkg-info (display metadata about a package)
- — forget (discard receipt data for the specified package)
- — expand (expand a flat .pkg to a folder)
- — flatten (reverse of expand)
- — check-signature (verify signature of a package)
Most .pkgs also contain a bom (Bill of Materials) file – and another command-line tool (lsbom) allows you to read the bom to list what’s in a .pkg.
Deleting logs
You can, from time to time, delete certain logs contained in /private/var/logs if you wish. Just don’t delete anything that is locked or in use by macOS.
Periodically, macOS will archive old logs by compressing and removing them. These log files will appear as .gz or .bz2 files.
If you don’t need these archived logs, you can delete them.
You can also remove logs from within the Console app itself. In both the Finder and in Console, you will need an admin password to remove protected logs.
Keep in mind that, when you delete log files from your Mac, those messages are gone forever and will no longer be available.
In the event you do delete a system log that is used by macOS, it will automatically re-create a new copy when it needs to write log messages out to disk. It’s best to restart your Mac after deleting logs to reset and refresh everything.
If you do need to keep some of the log files around for later but want to clear them from your Mac, be sure to make backup copies of the log files first.
Installer utilities
If you want to build your own .pkg installers, macOS has a built-in command line tool called pkgbuild. The third-party utility Package Builder ($25) from Araelium helps ease package assembly and builds.
Stephane Sudre has a free package builder called simply Packages.
Also check out the cool .pkg inspector tool Pacifist from CharlesSoft ($20).
One more great little installer utility is Suspicious Package from Mother’s Ruin. This utility lets you peek inside macOS installers without running them – allowing you to verify package signatures, see what an installer contains, and see what scripts an installer will run.
The macOS installer architecture is very robust and in fact goes all the way back to the very first release of Mac OS X in 2000. Actually, the .pkg architecture goes all the way back to macOS’s precursor, NeXTStep.
In a future article, we’ll look at common macOS installer errors and discuss how macOS installer packages are built and what to include in them.
Source link
