Installing OmniPTY

OmniPTY ships as a signed, notarized DMG for macOS 12 and later, on both Apple Silicon and Intel, and as a pacman package and a plain tarball for Linux on x86_64, Wayland or X11. The macOS build keeps itself up to date after that.

Install on macOS

1. Download the latest DMG (the same file as the button on omnipty.com; every version is on the releases page).
2. Open it and drag OmniPTY to Applications.
3. Launch it.

Every build is signed with a Developer ID certificate, notarized by Apple, and stapled, so Gatekeeper opens it like any other app — no right-click-to-open, no xattr -d.

Install with Homebrew

brew install --cask omnipty-terminal/tap/omnipty

This installs the same signed, notarized build as the DMG. The fully-qualified name taps omnipty-terminal/tap and marks just this cask as trusted in one step, so there is no separate brew tap or brew trust to run. To remove it: brew uninstall --cask omnipty.

Install on Linux

The Linux build runs on Wayland and X11, x86_64, on any distro with glibc 2.35 or newer — Ubuntu 22.04, Debian 12, Fedora 36 and later. It needs a Vulkan driver — any GPU from the last decade: Mesa's vulkan-radeon or vulkan-intel, or nvidia-utils — and libnotify (notify-send) for desktop notifications.

Arch and derivatives

git clone https://github.com/omnipty-terminal/omnipty.git
cd omnipty/packaging/aur/omnipty-bin
makepkg -si

The PKGBUILD in the repo fetches the release tarball below and installs it as a regular pacman package, omnipty-bin, launcher entry and icon included. To update, git pull and run makepkg -si again. An AUR listing will follow once AUR registration reopens; then it's yay -S omnipty-bin.

Any distro

Download the latest tarball (older versions are on the releases page), unpack it, and run the installer:

tar xzf omnipty-linux-x86_64.tar.gz
cd omnipty-*-linux-x86_64
./install.sh                          # into ~/.local — no root needed

sudo ./install.sh --prefix /usr/local  # or system-wide
./install.sh --uninstall              # removes what it installed

install.sh puts omnipty on your PATH, adds the .desktop launcher entry, and drops the icon into the hicolor theme, so OmniPTY shows up in your application launcher like anything else.

First run

On first launch OmniPTY writes a fully commented default config to ~/.config/omnipty/config.toml. Open it from inside the app with cmd-, (OmniPTY → Settings…) on macOS or ctrl-, on Linux, which opens it in the focused pane with your $EDITOR — or the desktop's text editor (open -t on macOS, xdg-open on Linux) if you have no $EDITOR set. Nothing is echoed at the prompt; the editor just appears.

See Configuration for what goes in that file.

The omnipty command

On macOS this is an optional one-line shim so you can open the app at a directory from any terminal. On Linux, omnipty is the binary itself, already on your PATH after install.sh or the pacman package, and takes the same arguments.

# macOS only, from a clone of the repo
sudo cp scripts/omnipty-cli /usr/local/bin/omnipty
sudo chmod +x /usr/local/bin/omnipty

omnipty            # open at the current directory
omnipty ~/Code     # open at a specific one
omnipty -e btop    # run a program in the first pane instead of the shell
omnipty --app-id org.omarchy.btop -e btop   # ...under its own window class, for window rules
omnipty --no-startup-commands   # restore pinned workspaces without running their commands

One difference: on Linux the command holds the terminal you ran it from until the window closes, the way alacritty and kitty do. Use omnipty . & to get your prompt back, or install scripts/omnipty-cli ahead of it on your PATH for the detached behaviour the macOS shim has.

As the default terminal on Linux

-e and --app-id are what xdg-terminal-exec passes to a terminal, and the .desktop entry declares them, so OmniPTY can be the terminal your desktop opens for you. Put it first in ~/.config/xdg-terminals.list:

omnipty.desktop

On Omarchy that covers super+return and the TUI launchers (omarchy launch tui btop, which opens btop in OmniPTY under the org.omarchy.btop app-id its window rules expect). A -e launch opens just that program: pinned workspaces stay where they are, and the pane closes when the program exits cleanly. A failure keeps its output on screen.

Upgrading from Oxide

OmniPTY was called Oxide until 0.9.0. An installed Oxide updates itself to OmniPTY like any other release: the bundle becomes OmniPTY.app, and config.toml, themes and pinned workspaces are copied from ~/.config/oxide and ~/.cache/oxide to the omnipty directories on first launch (the originals are left in place). A Dock icon pinned to the old Oxide.app path needs re-adding.

Homebrew: switch to the new cask so later upgrades keep arriving. --adopt keeps the OmniPTY.app the updater already put in place:

brew uninstall --cask --force oxide-terminal && brew install --cask --adopt omnipty-terminal/tap/omnipty

Dotfiles that read $OXIDE_SESSION or $OXIDE_VERSION keep working through 0.9.x; the new names are $OMNIPTY_SESSION and $OMNIPTY_VERSION. theme = "oxide" still selects the same palette, now also called omnipty.

Updating

On macOS, a copy running from an installed .app checks downloads.omnipty.com for a newer release on launch and every six hours after that. When one exists, OmniPTY downloads it in the background, verifies its signature against a key built into the app, and offers to install; one click swaps the bundle and relaunches. A download that fails the check is discarded, never installed. You can also check on demand from OmniPTY → Check for Updates… A failed download shows up as an error toast in the corner, and the first launch after an update shows a toast; click it to read the changelog in a new tab.

Version comparison is numeric on major.minor.patch, so a build with a higher version than the latest release is never "updated" backwards. Running through cargo run skips the check entirely.

On Linux there is no in-app install: an installed copy still checks, and when a newer release exists it shows a pill in the top-right corner — ↑ vX available — click for the release — that opens the release page. Update with git pull and makepkg -si (the pacman package) or by unpacking the new tarball and running its install.sh over the old one. cargo run builds never check.

Building from source

Building needs a couple of things a download does not:

• Rust, 2024 edition
• On macOS, full Xcode with the Metal toolchain — GPUI compiles Metal shaders at build time, and the Command Line Tools alone are not enough
• On Linux, the GPUI build dependencies. No Xcode, no Metal — the shaders are compiled for Vulkan.

# macOS
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
xcodebuild -downloadComponent MetalToolchain   # if the build asks

# Arch
sudo pacman -S --needed base-devel fontconfig freetype2 libxkbcommon \
  libxkbcommon-x11 libxcb wayland vulkan-icd-loader libnotify

# Debian / Ubuntu
sudo apt-get install pkg-config libfontconfig1-dev libfreetype6-dev \
  libwayland-dev libxkbcommon-dev libxkbcommon-x11-dev libx11-dev \
  libxcb1-dev libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev \
  libssl-dev libnotify-bin

Then:

git clone https://github.com/omnipty-terminal/omnipty.git
cd omnipty
cargo run                     # development build

# macOS
./scripts/bundle.sh           # release -> target/OmniPTY.app (ad-hoc signed)
cp -R target/OmniPTY.app /Applications/

# Linux
./scripts/linux-package.sh    # release -> target/omnipty-<version>-linux-x86_64.tar.gz
tar xzf target/omnipty-*-linux-*.tar.gz -C /tmp && /tmp/omnipty-*-linux-*/install.sh

Maintainers publish a release with ./scripts/release.sh, which takes the notes from CHANGELOG.md, builds the notarized DMG and uploads it twice: once for the website's download button and once as -update.dmg for the in-app updater, so the site's download count doesn't include updates.

The first build compiles GPUI and its shaders — expect several minutes. A locally bundled Mac app is ad-hoc signed rather than notarized; it runs fine on your own machine.

Uninstalling

# macOS
rm -rf /Applications/OmniPTY.app
sudo rm -f /usr/local/bin/omnipty   # if you installed the CLI shim

# Linux
pacman -R omnipty-bin      # the pacman package, or
./install.sh --uninstall          # from the unpacked tarball

# both
rm -rf ~/.config/omnipty      # your config
rm -rf ~/.cache/omnipty       # generated scripts, workspaces, window state

OmniPTY never writes to your dotfiles, so there is nothing to unpick in ~/.zshrc or ~/.bash_profile.