Installing Oxide

Oxide 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. Grab the latest DMG from the releases page (or from the button on oxideterminal.com).
2. Open it and drag Oxide 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 bobbycoleman-dev/tap/oxide-terminal

This installs the same signed, notarized build as the DMG. The fully-qualified name taps bobbycoleman-dev/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 oxide-terminal.

Install on Linux

The Linux build runs on Wayland and X11, x86_64. 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/bobbycoleman-dev/oxide.git
cd oxide/packaging/aur/oxide-terminal-bin
makepkg -si

The PKGBUILD in the repo fetches the release tarball below and installs it as a regular pacman package, oxide-terminal-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 oxide-terminal-bin.

Any distro

Grab oxide-<version>-linux-x86_64.tar.gz from the same releases page, unpack it, and run the installer:

tar xzf oxide-<version>-linux-x86_64.tar.gz
cd oxide-<version>-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 oxide on your PATH, adds the .desktop launcher entry, and drops the icon into the hicolor theme, so Oxide shows up in your application launcher like anything else.

First run

On first launch Oxide writes a fully commented default config to ~/.config/oxide/config.toml. Open it from inside the app with cmd-, (Oxide → 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 oxide command

On macOS this is an optional one-line shim so you can open the app at a directory from any terminal. On Linux, oxide 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/oxide-cli /usr/local/bin/oxide
sudo chmod +x /usr/local/bin/oxide

oxide            # open at the current directory
oxide ~/Code     # open at a specific one
oxide --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 oxide . & to get your prompt back, or install scripts/oxide-cli ahead of it on your PATH for the detached behaviour the macOS shim has.

Updating

On macOS, a copy running from an installed .app checks GitHub for a newer release on launch and every six hours after that. When one exists, Oxide downloads it in the background and offers to install; one click swaps the bundle and relaunches. You can also check on demand from Oxide → 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/bobbycoleman-dev/oxide.git
cd oxide
cargo run                     # development build

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

# Linux
./scripts/linux-package.sh    # release -> target/oxide-<version>-linux-x86_64.tar.gz
tar xzf target/oxide-*-linux-*.tar.gz -C /tmp && /tmp/oxide-*-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/Oxide.app
sudo rm -f /usr/local/bin/oxide   # if you installed the CLI shim

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

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

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