BleachBit on macOS

Progress

Updated: October 15, 2026

BleachBit on macOS is quickly making progress. Recent updates:

  • All non-GUI tests pass on macOS Tahoe (26) with Python 3.9
  • The BleachBit master branch includes a macOS test runner for testing all new code changes
  • macOS support added for popular cross-platform applications such as Firefox, Google Chrome, Brave, VLC, VS Code
  • master branch supports CLI and GTK GUI on macOS
  • master branch supports native macOS functionality such as cleaning Safari, macOS trash, and detecting the user's language
  • On an alternative branch, a wxPython-based GUI works easily without Homebrew or compiling Python wheels

Next steps

Future steps include: improving support for macOS-specific cleaners, testing, creating a .dmg (disk image), and digital signature.

Are you a macOS user who would like to shape the direction, keep informed, and be the first to try it out? Sign up using this survey form.

Mac Insiders

Another option: subscribe to GitHub issue 1863 and join the discussion here.

Also, follow the social accounts (top right of page) for updates.

Quick start guide for advanced users

If you are comfortable running commands on the CLI,
these guides will get you started.
These steps are a temporary requirement until the .DMG installer is ready.

GTK quick start

The master branch offers the CLI (command line interface) and GTK GUI.

# Dependencies (Homebrew Python + GTK 3)
brew install python gtk+3 pygobject3 adwaita-icon-theme

# Clone
git clone https://github.com/bleachbit/bleachbit.git
cd bleachbit

# Optional: Translations (gettext is keg-only, so add it to PATH)
brew install gettext
export PATH="$(brew --prefix gettext)/bin:$PATH"
make -C po local

# Venv from Homebrew's python (sees the brewed pygobject3)
/opt/homebrew/bin/python3 -m venv --system-site-packages .venv
source .venv/bin/activate
pip install -r requirements.txt

# If GTK libraries are not found at runtime:
export DYLD_LIBRARY_PATH=/opt/homebrew/lib  # /usr/local/lib on Intel

# Run (no args launches the GUI when GTK is importable)
python bleachbit.py

wxPython quick start

The wxPython GUI has a few advantages compared to GTK: native UI rendering, simpler dependencies, and unique GUI features like a table-based results view.

However, there are two disadvantages to wxPython. First, this branch is behind master and is missing some macOS-specific enhancements only in the master branch: for cleaners, you can simply copy the .xml files from master (commands not shown here). Second, the wxPython GUI is missing some features that GTK has.

# Clone
git clone https://github.com/bleachbit/bleachbit.git
cd bleachbit
git checkout wx-gui-mvp

# Venv (any python3 works: Homebrew, python.org, Xcode CLT)
python3 -m venv .venv
source .venv/bin/activate

# Dependencies: usual runtime deps + wxPython >= 4.2
pip install -r requirements.txt wxPython

# Run
python bleachbit-wx.py

TUI

The BleachBit experimental TUI (text user interface) also works on macOS.

# Clone and switch to the branch
git clone https://github.com/bleachbit/bleachbit.git
cd bleachbit
git switch --track origin/tui

# Venv (any python3 works)
python3 -m venv .venv
source .venv/bin/activate

# Dependencies (requirements.txt on this branch includes
#    textual>=1.0.0 and rich>=13.0.0)
pip install -r requirements.txt

# Run (no args launches the interactive TUI)
python bleachbit_tui.py

Links