Skip to main content

Native Mac OS UI elements with python

Project description


Display native dialogs, alerts, notifications, color pickers, and more with Python

GitHub Workflow Status Version PyPI - Downloads MIT Buy Me A Coffee

💥 This library is still a work in progress.

Useful links


  • Display dialogs
    • Dialog prompts
    • Icon support
  • Alerts
  • Choice dialogs
  • Notifications
    • Customize title, subtitle, and informational text
    • Customize icon
    • Schedulable
    • Callbacks (button pressed, reply text) – relevant stackoverflow answer
    • Fallback (AppleScript) notifications
  • Color picker
  • File/folder picker


Find the documentation in the docs/ folder


See the examples/ directory. Feel free to make a pull request to add more examples.

Show a dialog with the buttons "Go" (default) and "No" (to cancel) with the caution icon:

from aquaui import Dialog, Buttons, Icon

buttons = Buttons(["Go", "No"], default_button="Go", cancel_button="No")
result = Dialog("Hello!").with_buttons(buttons).with_icon(Icon.CAUTION).show()

Execute functions based on the button clicked:

from aquaui import Dialog, Buttons

button_one = "One"
button_two = "Two"
buttons = Buttons([button_one, button_two])

result = Dialog("Press a button").with_buttons(buttons).show()

if result.button_returned == button_one:
  print("Button One was pressed")
elif result.button_returned == button_two:
  print("Button Two was pressed")

Display a choice dialog with the options "Netflix" and "Prime Video"

from aquaui import Choice

provider = Choice("Choose the streaming platform").with_choices(["Netflix", "Prime Video"]).show()

If this example interests you, check out my other library Flixpy.

Display a notification:

Warning: please read the documentation before using notifications. There are additional dependencies to install.

from aquaui.notification.native_notification import Notification

notification = (
    .with_subtitle("This is the subtitle!")
    .with_informative_text("Isn't this informative?")
    .with_identity_image("assets/folder.png")  # the image on the right of the notification

Schedule a notification:

from aquaui.notification.native_notification import Notification

notification = Notification("Your pizza is here!").with_delay(15).send()
# 15 seconds delay

Build setup

Clone or fork the repository, then run

poetry shell

poetry install
pre-commit install

Make changes, then run tests with

pytest tests

Ensure that all tests pass.

Recommended editor settings
  "python.formatting.provider": "black",
  "editor.formatOnSave": true,
  "[python]": {
    "editor.insertSpaces": true,
    "editor.detectIndentation": false,
    "editor.tabSize": 4
  "python.linting.enabled": true,
  "python.linting.flake8Enabled": true,
  "python.linting.pylintEnabled": false,
  "python.pythonPath": "/Users/yourusername/.../aquaui-UIHDsdfS-py3.7"



Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

aquaui-0.0.1.post2.tar.gz (9.5 kB view hashes)

Uploaded source

Built Distribution

aquaui-0.0.1.post2-py3-none-any.whl (10.1 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page