pynib 0.1.14

Python-SwiftUI Bridge for macOS Status Bar Apps

nib

Build native macOS menu bar apps in Python.

Install

Requires macOS 14+ and Python 3.10+.

pip install pynib

Create a project

nib create myapp
cd myapp

This scaffolds a project with a pyproject.toml and a src/main.py entry point.

Write your app

import nib

def main(app: nib.App):
    app.icon = nib.SFSymbol(
        "apple.meditate", rendering_mode=nib.SymbolRenderingMode.HIERARCHICAL
    )
    app.title = "Your Nib app"
    app.menu = [
        nib.MenuItem(
            content=nib.VStack(
                controls=[
                    nib.Text("Custom Item"),
                    nib.Text(
                        "You can place any control you want!",
                        font=nib.Font.CAPTION,
                        foreground_color=nib.Color.WHITE.with_opacity(0.5),
                    ),
                ],
                alignment=nib.Alignment.LEADING,
            ),
            height=35,
        ),
        nib.MenuDivider(),
        nib.MenuItem("Quit", shortcut="cmd+q", action=app.quit),
    ]

    count = nib.Text("0", font=nib.Font.TITLE2)

    def increment():
        count.content = str(int(count.content) + 1)
    def decrement():
        count.content = str(int(count.content) - 1)

    app.build(
        nib.HStack(
            controls=[
                nib.Button(
                    content=nib.SFSymbol("minus"),
                    action=decrement
                ),
                count,
                nib.Button(
                    content=nib.SFSymbol("plus"),
                    action=increment
                ),
            ]
        )
    )

nib.run(main)

Run it

nib run main.py

This starts your app in dev mode with hot reload. Edit your code, save, and the app updates.

Build it

When you're ready to distribute:

nib build main.py

This produces a self-contained .app in dist/ that bundles a portable Python runtime, your code, and all dependencies. No Python installation needed on the target machine.

Flag	Effect
--native	Compile to native .so via Cython
--obfuscate	Strip debug info from .pyc
--no-compile	Keep .py source files
--icon icon.png	Custom app icon
--name "My App"	Override display name
--arch arm64	Target architecture

Build options can also go in pyproject.toml:

[tool.nib]
entry = "src/main.py"

[tool.nib.build]
name = "My App"
icon = "assets/icon.png"
identifier = "com.example.myapp"
native = true

Features

Nib includes views like Text, Button, TextField, Toggle, Slider, Picker, DatePicker, ColorPicker, Image, Video, Label, Link, ProgressView, Gauge, Markdown, Table, SecureField, TextEditor, Map, WebView, and ShareLink. Layouts include VStack, HStack, ZStack, ScrollView, List, Form, Section, NavigationStack, DisclosureGroup, Grid, and lazy grids. There's also charting with LineMark, BarMark, AreaMark, PointMark, RuleMark, RectMark, and SectorMark.

On the system side: notifications, global hotkeys, clipboard, file dialogs, drag and drop, camera, battery, connectivity, screen info, keychain, and launch at login. Settings get their own window with tabs and auto-persist to UserDefaults. The status bar icon supports a right-click context menu with nested items, shortcuts, and badges.

See the full documentation at bbalduzz.github.io/nib.

Architecture

License

MIT