Platypus: wrapping command line scripts in native macOS application bundles

What problem Platypus solves, and for whom

A shell script that works perfectly in Terminal is unusable to a colleague who has never opened Terminal. Platypus exists to close that gap. The README describes it as a developer tool that creates native Mac applications from command line scripts such as shell scripts or Python, Perl, Ruby, Tcl, JavaScript and PHP programs. The mechanism is stated plainly: the script is wrapped in an application bundle along with a slim app binary that runs the script.

The intended audience is narrow but real. The README lists installers, droplets, administrative applications, login items, status menu items, launchers and automations as the things Platypus makes easy. Those are all cases where a script already exists and the missing piece is a double-clickable icon with a sensible window. A droplet is the clearest example: an app that accepts files dropped onto it and passes their paths to the script as arguments. If your problem is a script that needs a real settings window, a database layer, or a multi-pane interface, Platypus is not the tool, because the interface choices are fixed presets rather than a general UI framework.

One detail worth weighing: the author's own note in the README says Platypus is very old software dating back to around 2003, that many beginner mistakes remain in the structure of the code, and that it is not how he would write it today. That is an honest signal about the codebase you would be reading if you need to patch it.

How the bundle wrapper actually works

The architecture visible in the repository splits into a few top-level directories. Application/ holds the Objective-C/Cocoa app, ScriptExec/ holds the script execution component, CLT/ holds the command line tool, Shared/ holds code used by more than one target, and Sparkle/ handles updates. The generated app is therefore not an interpreter: it is a bundle containing your script plus a binary whose job is to launch that script and relay its output back to the chosen interface.

The interface is a property of the generated app, not something you write. Platypus offers a progress bar, a text window showing script output, a WebKit HTML view, a status item menu, and a droplet that receives dragged and dropped files or text snippets. Those snippets are then passed to the script as arguments. Other per-app settings include the icon (custom or from presets), associated file types, bundle identifier, version and author, whether the app runs in the background via LSUIElement, whether it registers as a handler for URI schemes, whether it sends user notifications, and whether it runs with root privileges through the macOS Security Framework.

Configuration is reusable. Platypus calls saved app configurations profiles, and the repository ships a set of them under Examples/, including AdminPrivilegesDemo.platypus, SpeakDroplet.platypus, StatusMenuDemo.platypus, WebViewDroplet.platypus and WordCountService.platypus. Reading those files is the fastest way to understand which settings map to which behaviour, because the README itself does not enumerate every key.

Installing Platypus and building a first droplet

The README points to a direct download of Platypus 5.5.0, roughly 3.5 MB, a Universal ARM/Intel 64-bit app that requires macOS 11 or later and is Developer ID signed and notarized. There is no Homebrew formula or package manager step documented in the README; the download link is the install path for the GUI app.

For automation and build process integration, the README gives a separate procedure that installs the command line tool to /usr/local/bin/platypus. It fetches the release archive, unpacks it, and runs the installer script inside the app bundle:

curl -L -O https://github.com/sveinbjornt/Platypus/releases/download/v5.5.0/platypus5.5.0.zip
unzip -q platypus5.5.0.zip
cd Platypus.app/Contents/Resources
sudo bash InstallCommandLineTool.sh

After that, platypus is on your PATH. The README links the man page for the full flag set, and it is the reference you should read before scripting a build, because the README does not list the individual options.

If you want to build the app from source instead of downloading it, the README gives one command, run from the repository root with Xcode build tools present. The resulting application bundle lands in the products directory:

make build_unsigned

The Makefile also defines a clt target that cleans, builds ScriptExec and builds the CLI, and the repository has a Tests/ directory and a "CLT Tests" test target, so the command line tool is the part with an explicit test path.

A first real use: open the Platypus app, pick the Droplet interface, paste a short script that echoes the paths it receives, set an icon, and create the app. Then drag a file onto the result. According to the README, the dropped file's path arrives in the script as an argument, which is the whole droplet contract in one gesture.

Where Platypus stops being the right tool

The most important limitation is environmental, not technical. Platypus produces a macOS application bundle, and the README describes it as a developer tool for native Mac applications. Nothing in the README suggests Windows or Linux output. If your audience is mixed, you are building two things.

Second, the generated app depends on the interpreter being available on the machine that runs it. Platypus supports shell scripts, Python, Perl, Ruby, PHP, Swift, Expect, Tcl, AWK, JavaScript, Dart, AppleScript or any other user-specified interpreter, which is a wide list, but the app bundle wraps the script rather than bundling a runtime for it. A script written against a Python version that is not present on the target Mac is a failure mode you own, not one Platypus solves. The README does not document rollback or a way to pin an interpreter inside the bundle.

Third, root privileges. The README states that apps can execute scripts with root privileges via the macOS Security Framework. That is a real capability and also a real liability: an administrative app you distribute is an administrative app someone else can inspect and possibly misuse. Treat the AdminPrivilegesDemo.platypus example as documentation of a sharp edge, not a template to ship casually.

Finally, the interface presets are the ceiling. There is no documented path to a custom window layout beyond the WebKit HTML view, which means anything resembling a normal Mac preferences window has to be faked in HTML or abandoned.

Alternatives and how their approach differs

The obvious comparison is with tools that produce a self-contained executable rather than a bundle around a script. PyInstaller and similar packagers freeze an interpreter and your code into a single binary. That difference matters in exactly the case Platypus handles least well: a target machine without the right runtime. A frozen binary carries its runtime; a Platypus app assumes the system interpreter. The trade is size and build complexity against dependency risk.

A second comparison is with Automator and Shortcuts, which are built into macOS. Those compose existing actions through a graphical pipeline and are aimed at users who do not write code. Platypus is aimed at people who already have a script and want to keep it as the source of truth. If your logic is five lines of shell, Automator is less machinery. If your logic is a 400-line Python program, wrapping it in Platypus preserves it intact while an Automator workflow would force a rewrite.

A third is a plain shell script plus a .command file. That is the zero-dependency option and it works, but it opens Terminal, which is the exact outcome Platypus is designed to avoid. Choose Platypus when the visual presentation is the point; choose the .command file when it is not.

Maintenance, upgrade cost and licence terms

The repository is not archived, and the last push was on 2026-05-13. The release history shows v5.5.0 on 2025-12-02, v5.4.1 on 2022-10-22 and v5.4 on 2022-09-03, so the gap between v5.4.1 and v5.5.0 was roughly three years. That pattern suggests long quiet periods punctuated by feature releases, and it is the number to weigh if you depend on upstream fixes. The README claims continuous development and maintenance for over 20 years, which is true across the project's life but says nothing about the cadence of any given year.

Upgrade cost is low for the wrapper itself and higher for your scripts. Platypus ships an appcast feed, so the app can update through Sparkle, and profiles are saved configurations you can reuse across versions. Your own scripts are the part that ages: a Python 2 script wrapped in 2015 does not become a Python 3 script because Platypus released a new version.

On licensing, Platypus is BSD-3-Clause, copyright 2003-2025 Sveinbjorn Thordarson. The three conditions are the usual ones: keep the copyright notice and disclaimer in source redistributions, reproduce them in binary redistributions, and do not use the copyright holder's or contributors' names to endorse derived products without written permission. The practical consequence for anyone shipping a generated app is that the licence covers Platypus itself, while the scripts you wrap remain yours and carry your own obligations. This is a summary of the licence text in the repository, not legal advice.

Editorial conclusion

Platypus fits developers on macOS 11 or later who already have a working script and need to hand it to people who will not open Terminal, especially for droplets, installers, login items and status menu items. Skip it if you need cross-platform output, a full GUI toolkit, or an app you can build from source in CI without an Apple toolchain. Before committing, build one of the bundled Examples/*.platypus profiles end to end, confirm the resulting bundle launches on a clean Mac, and check whether your script's interpreter is present on that machine.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. Project website
3. README
4. Releases
5. sveinbjornt/Platypus on GitHub