5.0.2 • Public • Published


NPM version Build Status Windows Build Status Dependency Status

Auto-launch your app on login.

  • ⭐️ Launch any application or executable at startup / login / boot.
  • ⭐️ Supports Linux, Mac (via AppleScript or Launch Agent), and Windows.
  • ⭐️ Supports NW.js and Electron (with or without Squirrel; i.e. even if you're using Electron's built-in `autoUpdater`` API).
  • ⭐️ Auto-detects your app path for NW.js and Electron apps.
  • 😞 Not Mac App Store friendly. See Make this Mac App Store compatible for more information.


var AutoLaunch = require('auto-launch-patched');
var minecraftAutoLauncher = new AutoLaunch({
    name: 'Minecraft',
    path: '/Applications/',
    // handle error


npm install --save auto-launch


new AutoLaunch(options)

options - Object - String

The name of your app.

options.path - String (optional for NW.js and Electron apps)

The absolute path to your app.

For NW.js and Electron apps, you don't have to specify the path. We guess based on process.execPath.

options.isHidden - (Optional) Boolean

If true, we instruct the operating system to launch your app in hidden mode when launching at login. Defaults to false.

options.mac (Optional) object

For Mac-only options.

options.mac.useLaunchAgent (optional) Boolean.

By default, we use AppleScript to add a Login Item. If this is true, we use a Launch Agent to auto-launch your app. Defaults to false. For more information, see How does it work? (mac) below.


Sets your app to auto-launch at startup. Returns a Promise.


Disables your app from auto-launching at startup. Returns a Promise.


Returns a Promise which resolves to a Boolean; true if your app is set to launch on startup.

How does it work?


A Desktop Entry is created; i.e. a .desktop file is created in ~/.config/autostart/.

Note: if auto-launch is enabled and then your app is removed, this desktop entry file would be left behind on the user's machine.


AppleScript (default)

We execute an AppleScript command to instruct System Events to add or remove a Login Item for your app. There are no files involved. To see your Login Items, you can go to System Preferences, Users & Groups, then Login Items. End users can add or disable items (including your app) here also, but most typical users aren't aware of it.

Login Items screenshot

Note: This is not Mac App Store friendly; if you use it in your app, it will be rejected by the Mac App Store. We're only 99% sure on this as we haven't actually tried ourselves. See Make this Mac App Store compatible for more information.

Launch Agent

This is a file-based method like Linux's Desktop Entry method. We add a .plist file in the user's Library/LaunchAgents directory to create a Launch Agent for your app.


  • Launch Agents are intended for daemons / something without UI, which might be applicable depending on your app.
  • We think this method seems to be faster, as in to enable or disable auto-launching (there is no difference in the amount of time it takes your app to launch). Although, that's not really a concern.
  • You might not trust AppleScript.


  • Your app will not appear in the user's Login Items. Therefore the user can only toggle auto-launching inside your app, if you provide them with a setting of course (which you should!). This is not a huge deal as most users are not aware of Login Items preferences, but it would be ideal if your app appeared there.
  • If the user was to remove your app, the file would be left behind on the user's machine.

If you find that the AppleScript method doesn't work for you and this method does, please let us know by creating an issue.

Note: This is not Mac App Store friendly; if you use it in your app, it will be rejected by the Mac App Store as this reaches outside of the app sandbox. See Make this Mac App Store compatible for more information.


We add a registry entry under \Software\Microsoft\Windows\CurrentVersion\Run.

Note: If the user was to remove your app, this would be left in the registry, but that's not such a big deal. You can probably configure your uninstaller to unset it.


If you're using Squirrel.Windows, i.e. what's underneath Electron's built-in autoUpdater API on Windows, we add a registry entry for your app's Update.exe instead of your actual application. This is due to how Squirrel.Windows works under the hood. What if we didn't? Well, if the user started / restarted their machine after updating your app, it would launch the old version by mistake.

Would you like to contribute?

We're always open to your help and feedback. See our


npm i auto-launch-patched

DownloadsWeekly Downloads






Last publish


  • guerrerocarlos