Effortlessly run scripts when certain files change.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

5.5 KiB


Japanese transliteration for "watch"

Miru is a script that watches directories for changes. When specific changes take place, it runs scripts or commands you specify.

For example, you could watch your Downloads folder and then automatically remove image metadata.

The current version is: 1.1.0


(This is biased towards UNIX machines. If you're on Windows, look up the appropriate alternatives to the commands in steps 3, 6, and 7)

  1. Download the source files

  2. Extract and move the Miru-main/ folder to a permanent location, like /home/me/etc/

  3. Navigate to the Miru-main/ folder in your terminal, then run chmod +x Miru.py (you will need to give your shell scripts executable permission likewise)

  4. While staying in the terminal, run the following commands:

    • pip install watchdog (for watching directories)
    • pip install rich (for colorful formatting)
  5. Double-check the shebang at line 1 of Miru.py to accurately reflect the location of your Python installation. Default is #!/usr/bin/env python3.9

  6. Open your .bashrc (or .zshrc) file and add:

    alias miru="/home/me/etc/miru/Miru.py"
  7. Reconfigure your shell by quitting terminal or running source .bashrc

  8. Run miru --create to create an example configuration file (.miruconf) in your home folder.

Note: If you don't want to deal with the config file, for whatever reason, you can invoke Miru with the necessary information with the --command-line or -cl flag, like so: miru -cl any:::/path/:::command


Miru watches directories for certain events. Currently, it supports any, created, deleted, modified, and moved events.

Running miru without any arguments will start the Watcher. Also note that Miru only cares about the few specified arguments, and will not notice any others. Therefore, miru sheep does the same thing as miru --wabberjack and simply miru.

Miru Config Syntax

  • # is a comment in a .miruconf file.
  • Newlines (AKA empty lines) are allowed.

The basic syntax for a config line is (without square brackets):


Every part of this line is mandatory.

In practice, this is an example:


For most use cases, you'll probably want to create a bash script (.sh) instead of directly using a command. That way, you can also pass the changed file as an argument to your script, so your tasks don't become too expensive.

Note: Make sure your script/command can be invoked multiple times without consequence. If you watch for the modified event, your script will be invoked multiple times (for each file, sometimes twice depending on your system, and the parent folder).


Argument Shortcut Description
--create -c Create a .miruconf file in your home folder
--reset -r Reset and/or Delete the .miruconf file
--delete -d Delete the .miruconf file
--edit -e Easily edit the .miruconf file (with the editor of your choice)
--view -v Print the contents of the .miruconf file
--pass -p Passes the changed file or directory as a command line argument to the script you provided
--log -l Enable log output to a miru.log file in your home folder
--recursive -re Do a recursive walk of the filesystem for every change. You'd better know what you're doing.
--command-line -cl Ignore the .miruconf file and instead take the line directly as the third argument. This would look like: miru -cl any:::/path/:::command
--help -h Show this menu and exit.


You can pass multiple special arguments in one go. For example, if you want to log, pass the arguments, and do a recursive walk all at once, you can invoke Miru with miru --log --pass --recursive or miru -l -p -re


Q: Can I run multiple Watcher instances at a time?

Yes. So far, no bugs have been encountered. To do this, simply add more than one config line in the .miruconf file. If you encounter any issues with multiple Watcher processes, please open an issue.

Q: Why does it not run as a daemon?

It is preferred to have some sort of feedback. If you run it normally via a terminal, it'll output the files you watch, when they change, and when commands or scripts are invoked.

Obviously, if you don't want to see the output or have a terminal window open, you could add it as a startup application or a crontab job.

Q: How do I let my scripts know what files change?

  1. Either manually check the modification date of the files yourself; or
  2. Invoke miru with the -p or --pass flag, to pass the changed file as a command line argument.

Use Ctrl+C to stop the Watcher (A 1-2 second (or long) delay is expected.)


This project uses Watchdog to watch the underlying filesystem for changes. Miru is simply a complex wrapper to allow you to easily modify these settings on-the-fly, without modifying some source code. It also allows for more advanced features like logging to a file.

Watchdog is released under the Apache v2 license. No modifications to the source code was made.

Additionally, this project uses Rich for elegant and colorful logging. Rich is released under the MIT license