Skip to content
Get packs

Guide · Open source

How to use xbar: install it, add plugins and run scripts in the menu bar

Updated · written with AI from the project's own documentation and checked against our catalogue data

xbar is a free, open-source app for macOS that shows the output of any script or program in your menu bar, the strip at the top of your screen. It is a rewrite of the older BitBar app. This guide walks through installing xbar, finding the plugin folder, adding plugins and deciding whether it suits you. After reading it you will be able to get xbar running and load your first plugin.

xbarmatryer/xbar · ★ 18.1k · MIT

Quick start

  1. 1Check your macOS version. Confirm your Mac runs macOS Catalina (10.15) or newer, which the README lists as the minimum.
  2. 2Download xbar. Get the latest release from the xbar releases page on GitHub.
  3. 3Open the app. Launch xbar so its icon appears in the macOS menu bar.
  4. 4Locate the plugins folder. Find ~/Library/Application Support/xbar/plugins, where xbar keeps plugins.
  5. 5Add a plugin. Copy a plugin into the folder, or use Preferences > Plugins... to discover and manage plugins.
  6. 6Check the menu bar. Look for the plugin's output in the menu bar and open its menu for more detail.

Check that your Mac meets the requirements

xbar runs only on macOS. The README says it requires macOS Catalina or newer (version 10.15 or later). It is not described as available for Windows or Linux.

  • Supported: macOS Catalina (10.15) or newer
  • Not covered by the README: Windows, Linux, and macOS versions older than Catalina

Install xbar on macOS

The project's install method is a direct app download. Open the project's releases page on GitHub, download the latest xbar release, and open the app as you would any other Mac app.

The README contains no terminal install commands, so none are needed.

  • Go to the xbar releases page on GitHub and download the latest release.
  • Open the downloaded app. Its icon appears in the menu bar once it is running.

Find the plugins folder

Plugins are the scripts xbar runs and displays. They live in a folder on your Mac. According to the README, that folder is located at ~/Library/Application Support/xbar/plugins.

If you are moving from BitBar, copy your existing plugins into this folder to install them in xbar.

~/Library/Application Support/xbar/plugins

Add plugins from the menu or the plugin directory

To discover and manage plugins from inside the app, open an xbar menu and choose Preferences > Plugins. You can also browse the plugin repository online at xbarapp.com and download plugins from there.

To write your own plugin, the README points to the Writing plugins guide in the xbar-plugins repository on GitHub. Read that guide for the required script format, since this page does not reproduce it.

  • Open an xbar menu and choose Preferences > Plugins...
  • Browse the online plugin repository at xbarapp.com
  • Place plugin files in the plugins folder

Contribute a plugin or report an issue

The xbar-plugins repository on GitHub accepts plugin contributions. For the main xbar repository, the README asks people not to send pull requests. Open an issue and start a conversation first, because PRs will likely not be accepted.

  • Plugin contributions: github.com/matryer/xbar-plugins
  • Code changes to the main repo: open an issue first, do not send a pull request

What people use it for

  • Keeping a status check, such as a service's up or down state, visible in the menu bar
  • Showing a custom readout from your own script without opening a terminal window
  • Moving existing BitBar plugins to a maintained successor
  • Installing community plugins from the online plugin directory

Frequently asked questions

Is xbar free?

The README describes xbar as completely open source and it is licensed under the MIT licence. The source does not mention any paid tier, so the project presents it as free.

What macOS version does xbar need?

The README says xbar requires macOS Catalina or newer, meaning version 10.15 or later. Older versions of macOS are not supported according to the README.

Does xbar work on Windows or Linux?

The README describes xbar only as a macOS app. It is built with the Wails framework, which can target several platforms, but the README does not list Windows or Linux support, so do not assume it works there.

Where are xbar plugins stored?

Plugins are kept in ~/Library/Application Support/xbar/plugins. If you are coming from BitBar, move your plugins into that folder.

What is the difference between xbar and BitBar?

xbar is described in the README as a complete rewrite of BitBar, built from the ground up in Go using Wails. It is meant as the successor to BitBar and the README says users transitioning from BitBar should move their plugins to the new folder.

What are the alternatives to xbar?

The comparable projects listed for this guide are BitBar, SwiftBar and Hammerspoon. BitBar is the original app that xbar rewrites. SwiftBar and Hammerspoon are other macOS tools in the same general space, but this guide does not compare their features in detail.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

xbar suits Mac users who want a script's output permanently visible in the menu bar, especially people moving from BitBar or developers who want quick status readouts. It is a poor choice for Windows or Linux users, for Macs older than Catalina, or for anyone who wants to submit code changes through pull requests.

Install options & downloads