Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

Clean up your filesystem

Project description


Pushbroom is a tool designed to help keep your filesystem clear of clutter. Certain directories, such as your downloads directory, tend to accumulate a large amount of old files that take up space. Over time, this clutter can accumulate to a significant amount of storage space. Pushbroom gives you an easy way to remove these old files.

Pushbroom is written in Python and should therefore work on any platform that can run Python. For now, it is only officially supported for macOS and Linux.


Homebrew (macOS only)

Install via Homebrew:

brew install gpanders/tap/pushbroom

Copy and modify the included pushbroom.conf file to ~/.config/pushbroom/config and use brew services start gpanders/tap/pushbroom to start the automatic launchd daemon:

cp /usr/local/etc/pushbroom.conf ~/.config/pushbroom/config
brew services start gpanders/tap/pushbroom

Pushbroom will run once every hour.


Install using pipx:

pipx install pushbroom

Copy the example configuration file to ~/.config/pushbroom/config or create your own from scratch.

From source

Check the releases page for the latest release. Extract the archive and copy the files to their correct locations:

tar xzf pushbroom-vX.Y.Z.tar.gz
cd pushbroom-vX.Y.Z
cp bin/pushbroom /usr/local/bin/pushbroom
cp pushbroom.conf ~/.config/pushbroom/config


Pushbroom can be run from the command line using:


Use pushbroom --help to see a list of command line options.


The Pushbroom configuration file is organized into sections where each section represents a directory path to monitor. The default configuration file looks like this:

Path = ~/Downloads
Trash = ~/.Trash
NumDays = 30

This means that, by default, Pushbroom will monitor your ~/Downloads folder and move any file or folder older than 30 days into your ~/.Trash directory.

If you don't want to move files into ~/.Trash but instead want to just delete them, simply remove the Trash option:

Path = ~/Downloads
NumDays = 30

The name of the section (Downloads in this example) is not important and can be anything you want:

[Home Directory]
Path = ~
NumDays = 90

You can also specify an Ignore parameter to instruct Pushbroom to ignore any files or directories that match the given glob:

Path = ~/Downloads
NumDays = 30
Ignore = folder_to_keep

Similarly, you can specify Match to have Pushbroom only remove files that match one of the given patterns:

[Vim Backup Directory]
Path = ~/.cache/vim/backup
NumDays = 90
Match = *~

Both Ignore and Match can be a list of patterns separated by commas.

[Home Directory]
Path = ~
NumDays = 365
Match = .*
Ignore = .local, .config, .cache, .vim

Note that .* is not a regular expression for "match everything", but rather a glob expression for "all files that start with a period".

The following configuration items are recognized in pushbroom.conf:



Absolute path to a directory to monitor. Tildes (~) are expanded to the user's home directory.


Specify where to move files after deletion. If omitted, files will simply be deleted.



Number of days to keep files in Path before they are removed.


Default: None

List of glob expression patterns of files or directories to ignore.


Default: *

List of glob expression patterns of files or directories to remove. If omitted, everything is removed.


Default: False

Securely delete files before removing them. Note that this option is mutually exclusive with the Trash option, with Trash taking precedence if both options are used.


If installed via Homebrew then Pushbroom can be set to run once every hour using

brew services start gpanders/tap/pushbroom

Another option is to install a crontab entry

0 */1 * * * /usr/local/bin/pushbroom

If you are using a Linux distribution that uses systemd, you can copy the systemd service file to ~/.local/share/systemd/ and enable the service with

systemctl --user enable --now pushbroom

Note that you may need to change the path to the pushbroom script in the service file depending on your method of installation.

Similar Work

  • Belvedere: An automated file manager for Windows
  • Hazel: Automated Organization for your Mac

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pushbroom, version 0.2.1
Filename, size File type Python version Upload date Hashes
Filename, size pushbroom-0.2.1-py3-none-any.whl (7.7 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size pushbroom-0.2.1.tar.gz (7.0 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page