rumps

To bundle a rumps application into a standalone .app bundle, use the py2app library.

When configuring your setup.py, you must include 'rumps' in the packages list within the py2app options.

For status bar-based applications that should run in the background (without a Dock icon or the ability to be tabbed to in the App Switcher), set 'LSUIElement': True in the plist section of your options.

from setuptools import setup

APP = ['example_class.py']
DATA_FILES = []
OPTIONS = {
    'argv_emulation': True,
    'plist': {
        'LSUIElement': True,
    },
    'packages': ['rumps'],
}

setup(
    app=APP,
    data_files=DATA_FILES,
    options={'py2app': OPTIONS},
    setup_requires=['py2app'],
)

It is not recommended to use virtualenv with rumps due to issues with how the Python executable is copied. Instead, use the standard venv module (included with Python 3) to ensure proper functionality.

python3 -m venv env

To view informational messages and debug your application, enable debug_mode by calling rumps.debug_mode(True) in your code.

import rumps
rumps.debug_mode(True)

To create a standalone macOS application, use py2app. Ensure rumps is included in the packages list in your OPTIONS. For background apps (no Dock icon), set 'LSUIElement': True in the plist configuration.

Example setup.py:

from setuptools import setup

APP = ['example_class.py']
DATA_FILES = []
OPTIONS = {
    'argv_emulation': True,
    'plist': {
        'LSUIElement': True,
    },
    'packages': ['rumps'],
}

setup(
    app=APP,
    data_files=DATA_FILES,
    options={'py2app': OPTIONS},
    setup_requires=['py2app'],
)

Then run the following command to build the app:

python setup.py py2app

Once you have configured your setup.py with the necessary rumps package requirements and py2app options, run the following command to build the standalone .app bundle:

python setup.py py2app

Install the rumps package using pip. Note that you may need sudo if installing to a system-wide location.

pip install rumps

Install the rumps package directly from the source code using setup.py. Note that you may need sudo if installing to a system-wide location.

python setup.py install

When initializing a rumps.App, you can use the quit_button parameter to customize the text of the quit button or remove it entirely by passing None.

Warning: If you set quit_button=None, you must provide an alternative way to exit the application (e.g., a menu item that calls rumps.quit_application()), otherwise you will have to force quit the process.

# Removing the default quit button
app = rumps.App('Hallo Thar', menu=['Print Something', 'On/Off Test', 'Clean Quit'], quit_button=None)

# Providing an alternative exit method
@rumps.clicked('Clean Quit')
def clean_up_before_quit(_):
    rumps.quit_application()

app.run()

When testing a .app bundle generated via py2app, using the standard open {your app name}.app command will hide debug messages. To see the output, you must run the executable directly from the terminal.

If your app is in the default dist folder, run the executable using the following path structure:

./dist/{your app name}.app/Contents/MacOS/{your app name}

To create a macOS status bar application, subclass rumps.App and use decorators like @rumps.clicked(name) to define callback functions for menu items. You can trigger system alerts using rumps.alert() and notifications using rumps.notification(). To start the application, call the .run() method on your class instance.

import rumps

class AwesomeStatusBarApp(rumps.App):
    @rumps.clicked("Preferences")
    def prefs(self, _):
        rumps.alert("jk! no preferences available!")

    @rumps.clicked("Silly button")
    def onoff(self, sender):
        sender.state = not sender.state

    @rumps.clicked("Say hi")
    def sayhi(self, _):
        rumps.notification("Awesome title", "amazing subtitle", "hi!!1")

if __name__ == "__main__":
    AwesomeStatusBarApp("Awesome App").run()

To build a standard rumps application, subclass rumps.App and implement your logic within methods. You can define the menu items in the __init__ method and use the @rumps.clicked decorator to register callback functions for specific menu items.

import rumps

class AwesomeStatusBarApp(rumps.App):
    def __init__(self):
        super(AwesomeStatusBarApp, self).__init__("Awesome App")
        self.menu = ["Preferences", "Silly button", "Say hi"]

    @rumps.clicked("Preferences")
    def prefs(self, _):
        rumps.alert("jk! no preferences available!")

    @rumps.clicked("Silly button")
    def onoff(self, sender):
        sender.state = not sender.state

    @rumps.clicked("Say hi")
    def sayhi(self, _):
        rumps.notification("Awesome title", "amazing subtitle", "hi!!1")

if __name__ == "__main__":
    AwesomeStatusBarApp().run()