OmniPTY / docs
Docs / Getting started / Installation

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.

Fonts are included. JetBrainsMono Nerd Font Mono is compiled into the binary, so powerline separators, git glyphs, and file-tree icons all render on a machine with no Nerd Font installed. Install your own and point font.family at it whenever you like — GPUI consults in-memory fonts before system ones, so a locally installed copy of the same family behaves identically.

Windows (closed beta)

OmniPTY for Windows is in a closed beta. To join, request access at beta.omnipty.com. Once you're approved, you'll get a key by email; enter it on the same page to download the installer (recommended) or a portable zip. Both are code-signed.

The beta runs on Windows 10 (1903) or later and Windows 11, x64. New panes open PowerShell 7 when it's installed, then Windows PowerShell, then cmd; Git Bash works too (shell.program). Beta builds tell you when a newer one is out: download it from the beta page with the same key and run the installer over the top.

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, choose OmniPTY → Install omnipty CLI (or run it from the command palette): it asks for your password and puts a small shim at /usr/local/bin/omnipty, 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.

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

On macOS, with OmniPTY already running, omnipty opens a new window at the directory, and flags such as -e only apply when the command is what launches the app. Dropping a folder on the Dock icon also opens a window there.

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.

Downloaded installers live in ~/.cache/omnipty/updates/. Each launch deletes the ones for the version you're running or older, so they don't accumulate; a DMG for a newer release is kept.

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.