Skip to content

Instantly share code, notes, and snippets.

@anton-petrov
Forked from stevekm/launchctl_man.md
Created April 4, 2023 18:22
Show Gist options
  • Save anton-petrov/72895d2c3e52987bd20f83562aad61f1 to your computer and use it in GitHub Desktop.
Save anton-petrov/72895d2c3e52987bd20f83562aad61f1 to your computer and use it in GitHub Desktop.
macOS OS X login items

[source]

This manual page is for Mac OS X version 10.9

If you are running a different version of Mac OS X, view the documentation locally:

    In Terminal, using the man(1) command

Reading manual pages

Manual pages are intended as a quick reference for people who already understand a technology.

    To learn how the manual is organized or to learn about command syntax, read the manual page for manpages(5).

    For more information about this technology, look for other documentation in the Apple Developer Library.

    For general information about writing shell scripts, read Shell Scripting Primer.



launchctl(1)              BSD General Commands Manual             launchctl(1)

NAME
     launchctl -- Interfaces with launchd

SYNOPSIS
     launchctl [subcommand [arguments ...]]

DESCRIPTION
     launchctl interfaces with launchd to load, unload daemons/agents and generally control launchd.
     launchctl supports taking subcommands on the command line, interactively or even redirected from stan-dard standard
     dard input.  These commands can be stored in $HOME/.launchd.conf or /etc/launchd.conf to be read at the
     time launchd starts.

SUBCOMMANDS
     load [-wF] [-S sessiontype] [-D domain] paths ...
              Load the specified configuration files or directories of configuration files.  Jobs that are
              not on-demand will be started as soon as possible.  All specified jobs will be loaded before
              any of them are allowed to start.  Note that per-user configuration files (LaunchAgents) must
              be owned by the user loading them. All system-wide daemons (LaunchDaemons) must be owned by
              root. Configuration files must not be group- or world-writable. These restrictions are in
              place for security reasons, as allowing writability to a launchd configuration file allows one
              to specify which executable will be launched.

              Note that allowing non-root write access to the /System/Library/LaunchDaemons directory WILL
              render your system unbootable.

              -w       Overrides the Disabled key and sets it to false. In previous versions, this option
                       would modify the configuration file. Now the state of the Disabled key is stored
                       elsewhere on-disk.

              -F       Force the loading of the plist. Ignore the Disabled key.

              -S sessiontype
                       Some jobs only make sense in certain contexts. This flag instructs launchctl to look
                       for jobs in a different location when using the -D flag, and allows launchctl to
                       restrict which jobs are loaded into which session types. Currently known session
                       types include: Aqua, LoginWindow, Background, StandardIO and System.

              -D domain
                       Look for plist(5) files ending in *.plist in the domain given. Valid domains include
                       "system," "local," "network" and "all." When providing a session type, an additional
                       domain is available for use called "user." For example, without a session type given,
                       "-D system" would load from property list files from /System/Library/LaunchDaemons.
                       With a session type passed, it would load from /System/Library/LaunchAgents.

     unload [-w] [-S sessiontype] [-D domain] paths ...
              Unload the specified configuration files or directories of configuration files.  This will
              also stop the job if it is running.

              -w       Overrides the Disabled key and sets it to true. In previous versions, this option
                       would modify the configuration file. Now the state of the Disabled key is stored
                       elsewhere on-disk.

              -S sessiontype
                       Some jobs only make sense in certain contexts. This flag instructs launchctl to look
                       for jobs in a different location when using the -D flag, and allows launchctl to
                       restrict which jobs are loaded into which session types. Currently known session
                       types include: Aqua, LoginWindow, Background, StandardIO and System.

              -D domain
                       Look for plist(5) files ending in *.plist in the domain given. Valid domains include
                       "system," "local," "network" and "all." When providing a session type, an additional
                       domain is available for use called "user." For example, without a session type given,
                       "-D system" would load from property list files from /System/Library/LaunchDaemons.
                       With a session type passed, it would load from /System/Library/LaunchAgents.

     submit -l label [-p executable] [-o path] [-e path] -- command [args]
              A simple way of submitting a program to run without a configuration file. This mechanism also
              tells launchd to keep the program alive in the event of failure.

              -l label
                       What unique label to assign this job to launchd.

              -p program
                       What program to really execute, regardless of what follows the -- in the submit sub-command. subcommand.
                       command.

              -o path  Where to send the stdout of the program.

              -e path  Where to send the stderr of the program.

     remove job_label
              Remove the job from launchd by label.

     start job_label
              Start the specified job by label. The expected use of this subcommand is for debugging and
              testing so that one can manually kick-start an on-demand server.

     stop job_label
              Stop the specified job by label. If a job is on-demand, launchd may immediately restart the
              job if launchd finds any criteria that is satisfied.  Non-demand based jobs will always be
              restarted. Use of this subcommand is discouraged.  Jobs should ideally idle timeout by them-selves. themselves.
              selves.

     list [-x] [label]
              With no arguments, list all of the jobs loaded into launchd in three columns. The first column
              displays the PID of the job if it is running.  The second column displays the last exit status
              of the job. If the number in this column is negative, it represents the negative of the signal
              which killed the job.  Thus, "-15" would indicate that the job was terminated with SIGTERM.
              The third column is the job's label.

              Note that you may see some jobs in the list whose labels are in the style "0xdeadbeef.anony-mous.program". "0xdeadbeef.anonymous.program".
              mous.program".  These are jobs which are not managed by launchd, but, at one point, made a
              request to it.  launchd claims no ownership and makes no guarantees regarding these jobs. They
              are stored purely for bookkeeping purposes.

              Similarly, you may see labels of the style "0xdeadbeef.mach_init.program". These are legacy
              jobs that run under mach_init emulation. This mechanism will be removed in future versions,
              and all remaining mach_init jobs should be converted over to launchd.

              If [label] is specified, prints information about the requested job. If [-x] is specified, the
              information for the specified job is output as an XML property list.

     setenv key value
              Set an environmental variable inside of launchd.

     unsetenv key
              Unset an environmental variable inside of launchd.

     getenv key
              Get an environmental variable inside of launchd.

     export   Export all of the environmental variables of launchd for use in a shell eval statement.

     getrusage self | children
              Get the resource utilization statistics for launchd or the children of launchd.

     log [level loglevel] [only | mask loglevels...]
              Get and set the syslog(3) log level mask. The available log levels are: debug, info, notice,
              warning, error, critical, alert and emergency.

     limit [cpu | filesize | data | stack | core | rss | memlock | maxproc | maxfiles] [both [soft | hard]]
              With no arguments, this command prints all the resource limits of launchd as found via
              getrlimit(2).  When a given resource is specified, it prints the limits for that resource.
              With a third argument, it sets both the hard and soft limits to that value.  With four argu-ments, arguments,
              ments, the third and forth argument represent the soft and hard limits respectively.  See
              setrlimit(2).

     shutdown
              Tell launchd to prepare for shutdown by removing all jobs.

     umask [newmask]
              Get or optionally set the umask(2) of launchd.

     bslist [PID | ..] [-j]
              This prints out Mach bootstrap services and their respective states. While the namespace
              appears flat, it is in fact hierarchical, thus allowing for certain services to be only avail-able available
              able to a subset of processes. The three states a service can be in are active ("A"), inactive
              ("I") and on-demand ("D").

              If [PID] is specified, print the Mach bootstrap services available to that PID. If [..] is
              specified, print the Mach bootstrap services available in the parent of the current bootstrap.
              Note that in Mac OS X v10.6, the per-user Mach bootstrap namespace is flat, so you will only
              see a different set of services in a per-user bootstrap if you are in an explicitly-created
              bootstrap subset.

              If [-j] is specified, each service name will be followed by the name of the job which regis-tered registered
              tered it.

     bsexec PID command [args]
              This executes the given command in the same Mach bootstrap namespace hierachy as the given
              PID.

     bstree [-j]
              This prints a hierarchical view of the entire Mach bootstrap tree. If [-j] is specified, each
              service name will be followed by the name of the job which registered it.  Requires root priv-ileges. privileges.
              ileges.

     managerpid
              This prints the PID of the launchd which manages the current bootstrap.

     manageruid
              This prints the UID of the launchd which manages the current bootstrap.

     managername
              This prints the name of the launchd job manager which manages the current bootstrap.  See Lim-itLoadToSessionType LimitLoadToSessionType
              itLoadToSessionType in launchd.plist(5) for more details.

     help     Print out a quick usage statement.

ENVIRONMENTAL VARIABLES
     LAUNCHD_SOCKET
              This variable informs launchctl how to find the correct launchd to talk to. If it is missing,
              launchctl will use a built-in default.

FILES
     ~/Library/LaunchAgents         Per-user agents provided by the user.
     /Library/LaunchAgents          Per-user agents provided by the administrator.
     /Library/LaunchDaemons         System wide daemons provided by the administrator.
     /System/Library/LaunchAgents   Mac OS X Per-user agents.
     /System/Library/LaunchDaemons  Mac OS X System wide daemons.

SEE ALSO
     launchd.plist(5), launchd.conf(5), launchd(8)

Darwin                            1 May, 2009                           Darwin

[source]

Type 	Location 	Run on behalf of
User Agents 	~/Library/LaunchAgents 	Currently logged in user
Global Agents 	/Library/LaunchAgents 	Currently logged in user
Global Daemons 	/Library/LaunchDaemons 	root or the user specified with the key UserName
System Agents 	/System/Library/LaunchAgents 	Currently logged in user
System Daemons 	/System/Library/LaunchDaemons 	root or the user specified with the key UserName

[source]

Working Mac

By Joe Kissell, Senior Contributor, Macworld | Sep 2, 2013 3:30 AM PT How-To Take control of startup and login items

Related Video

How to bulk delete iPhone photos (1:21) Latest Reviews

Apple OS X Mavericks
David Boyes PicFrame 2.6.1 for Mac
Move to Apple Music 1.1

When you turn on your Mac, various apps, add-ons (such as menu extras), and invisible background processes open by themselves. Usually these automated actions are exactly what you want, but you may sometimes see items running—either visibly or according to a listing in Activity Monitor (located in /Applications/Utilities)—that you don’t recall adding yourself. Where do they come from? Because such items can increase your Mac’s startup time (and may decrease its performance), you’ll want your machine to load only items that are useful to you. Here’s a quick primer on the various kinds of startup and login items and how to manage them. Login items

Open the Users & Groups pane of System Preferences and click the Login Items tab, and you’ll see a list of apps (and even files and folders) that open every time you log in. (This list is different for each user account on your Mac.) More often than not, items appear in this list because apps added them to it. Most apps that do so ask you for permission first or offer an ‘Open at Login’ checkbox for you to check, but not all are so well behaved. In any case, you can add an item to the list manually by clicking the plus sign (+) button, or remove an item by selecting it and clicking the minus sign (-) button. Everything in the Login Items list—whether added by you or by an app—opens automatically when you log in. Startup items

Earlier versions of OS X relied on two folders—/Library/StartupItems and /System/Library/StartupItems—to hold items designated to load when you start your Mac. Apple now discourages the use of startup items, but some programs (mostly older apps) still use this mechanism. Normally your /System/Library/StartupItems folder should be empty; but if it contains something that you don’t use anymore, you can drag the unwanted item to the Trash to prevent it from loading automatically the next time you start your Mac. Launch daemons and agents

Since OS X 10.4 Tiger, Apple has given developers another mechanism for launching items automatically: launch daemons and agents, controlled by the launchd process. This approach provides more flexibility than either login items or startup items, but it is less transparent to users.

Behind the UNIX curtain: Instead of opening apps directly, launchd loads specially formatted .plist documents (XML preference files) that specify what should launch and under what circumstances. Sometimes these launch items run constantly in the background, sometimes they run at scheduled intervals, and sometimes they run as needed—for example, in response to an event such as a change in a certain file or folder—and then quit.

The .plist files that launchd uses can occupy any of five folders, and their location determines when the items load and with what privileges:

Items in /Library/LaunchDaemons and /System/Library/LaunchDaemons load when your Mac starts up, and run as the root user.

Items in /Library/LaunchAgents and /System/Library/LaunchAgents load when any user logs in, and run as that user.

Items in /Users/your-username/Library/LaunchAgents load only when that particular user logs in, and run as that user.

Keep your hands off of some: Of those five folders, the two located in the /System folder (/System/Library/LaunchDaemons and /System/Library/LaunchAgents) are for components included as part of OS X, and you should resist the temptation to remove or alter them—they’re essential to keep your Mac running correctly.

Modify others as you like: As for the items in the other folders, feel free to browse through them and see what’s there. You can modify them—for instance, to disable them or to change how often they run—but before you do, you should understand a few things about how they work.

When you start your Mac or log in, the launch items in the relevant folders are loaded (that is, registered with the system) unless they have a Disabled flag set. Thereafter, their instructions will be carried out until you restart, even if you drag the launch item to the Trash. To see a list of all the currently loaded launch items on your Mac, open Terminal (in /Applications/Utilities) and type launchctl list and then press Return.

If you want to stop a launch item from running without your having to restart, open Terminal and type launchctl unload followed by a space and the full path to the launch item. (An easy way to add an item’s full path is to drag it to the Terminal window.) For example, take this code:

launchctl unload ~/Library/LaunchAgents/com.apple.FolderActions.enabled.plist

It unloads the launch agent that enables AppleScript folder actions. Repeat the command with load instead of unload to turn it back on.

Because most launch items run on a schedule or on demand, and because any of them could be disabled, the fact that something is present in one folder doesn’t necessarily mean the process it governs is currently running. To see what’s running at the moment, open Activity Monitor—but bear in mind that the name of a given process as shown in Activity Monitor might not resemble the name of the .plist file that tells OS X to launch it.

Try a helpful utility: For seeing what launch items do—or for enabling or disabling them, or for deleting them (except those in the /System folder)—without any futzing in Terminal, my favorite tool is Peter Borg’s $10 Lingon X. There’s also a less-expensive Lingon 3, but it can do its work only on the current user’s launch items, which makes it much less powerful. Lingon X provides a friendly graphical interface rather than an inscrutable XML file, although you’ll still need a little geek mojo to understand some of its capabilities. Lingon X provides a user-friendly interface for viewing and editing launch items. Spontaneously reopening apps at startup If the checkbox is selected (as shown here) when you shut down or restart, whatever apps are open at that time will reopen automatically.

By default, when you restart your Mac, OS X 10.7 Lion and later reopen whatever applications and documents were open when you shut down. Whether this happens depends on the decision you make when you choose Restart or Shut Down from the Apple menu. In the dialog box that appears, if the ‘Reopen windows when logging back in’ checkbox is selected, the items will reopen; if not, not. However, you must make this decision before you shut down or restart, and it’s all or nothing—if you want to open only specific items, you’ll have to uncheck this box and add the items that you want to open at login to Login Items. Other explanations for mystery processes

Although the methods I’ve mentioned so far are the most common ways to launch apps automatically in OS X, they aren’t the only ones. If you have a mystery process that you can’t track down in any of these places, it could also be one of these:

A kernel extension: Kernel extensions, or kexts, live in /System/Library/Extensions and load at startup. They provide low-level features such as processing audio and adding support for peripherals. Most kexts on your Mac are part of OS X. The safest way to remove a third-party kext is to run an uninstaller provided by the developer.

A cron job: Cron is a Unix scheduling utility built into OS X. The easiest way to view and edit cron jobs without using Terminal is to download the free Cronnix utility by Sven A. Schmidt.

A login script: Login scripts, like startup items, were used in older versions of OS X but are now deprecated. To comment on this article and other Macworld content, visit our Facebook page or our Twitter feed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment