macmenuqbt 0.2.0

macOS menu bar app to show qBittorrent torrents status.

MacMenu-qBittorrent 🍏

MacMenu-qBittorrent is a lightweight macOS menu bar app that connects to qBittorrent's Web UI and displays active torrents with their progress and other stuff directly in your Mac menu bar.

---

Features

• Runs natively on macOS as a menu bar application.
• Connects to qBittorrent Web UI via qbittorrent-api.
• Launch qBittorent automatically
• Displays all active torrents with progress percentages and many other stuff in the menu bar.
• Configuration displaying
• Auto-refreshes torrent status at configurable intervals.
• Configurable connection parameters (host, port, username, password).
• Simple and clean UI using rumps.

---

Screenshot

• This is the default view:

• Status table (see also screenshot):

  Status	Emoji	Description
  downloading	⬇️	Downloading
  resumed	⬇️	Download resumed
  running	⬇️	Running / in progress
  forcedDL	⬇️	Forced download
  seeding	🌱	Seeding (uploading)
  completed	✅	Download completed
  paused	⏸️	Paused
  stopped	⏸️	Stopped
  inactive	⏸️	Inactive
  active	🔄	Active / operation in progress
  stalled	⚠️	Stalled / waiting
  stalled_uploading	⚠️	Upload stalled
  stalled_downloading	⚠️	Download stalled
  checking	🔍	Checking files
  moving	📦	Moving files
  errored	❌	Error encountered
  all	📋	All torrents
  unknown	❓	Unknown status

  

• All options enabled:

  Simply click on them to activate them.

• Change the order as you wish:

  

Install standalone MacMenuqBt (MMqBt)

1. Download MMqBt.appand open the DMG

   Double-click the MMqBt.dmg file you downloaded. A window will open showing the contents of the disk image.

2. Drag and drop the app

   In the window, you will see:

   • MMqBt.app – the application itself
   • Applications shortcut – a link to your Applications folder

3. Drag MMqBt.app onto the Applications shortcut. This will copy the app into your Applications folder.

4. Launch MMqBt

   • Open the Applications folder
   • Double-click MMqBt.app to start the app

⚠️ First launch: macOS may warn that the app is from an unidentified developer.

Setting up MMqBt

When you launch MMqBt for the first time, the app will need to connect to your qBittorrent client. For this to work, you’ll need to provide the following information in the app’s settings Credentials login:

Host – The IP address or hostname of the machine running qBittorrent. (Example: 127.0.0.1 if it’s on the same computer, or your LAN IP if remote.)

Port – The WebUI port configured in qBittorrent (default: 8080).

Username – The username you use to log into the qBittorrent WebUI.

Password – The matching password.

💡 Why is this required? MMqBt uses qBittorrent’s WebUI API to read torrent information and manage notifications. Without these credentials, the app cannot access your torrent list or status updates.

Tip:

• Make sure the qBittorrent WebUI is enabled:

  Open qBittorrent → Tools → Options → Web UI.

• Check "Enable the Web User Interface (Remote Control)".

• Note the IP, port, and credentials.

Once set up, MMqBt will remember your credentials locally (they are not sent anywhere else) and will automatically reconnect each time you start the app.

Installation via PyPI

1. Ensure you have Python >=3.8 installed on your Mac

2. Install the package from PyPI

   pip install macmenuqbt
   

---

Usage from the command line

Run the app from your terminal (or create a shortcut) — this will start the menu bar app:

macmenuqbt
# or the alias
mmqbt

Available options:

macmenuqbt --host localhost --port 8080 --username admin --password 123456 --interval 5

Argument	Alias(s)	Description	Default Value
--host	-H	qBittorrent Web UI host	localhost
--port	-P	qBittorrent Web UI port	8080
--username	-U	qBittorrent Web UI username	admin
--password	-PSW	qBittorrent Web UI password	123456
--interval	-I	Update interval in seconds	5
--version	-V	Show program version and exit
--help		Show this help message and exit

For help and version:

macmenuqbt --help 2805
macmenuqbt --version

Usage as a Python module

You can also embed Menubar-qBittorrent in your own Python scripts by calling its main() function with parameters:

from macmenuqbt.core import main as mmqbt

mmqbt(
    host="localhost",
    port=8080,
    username="admin",
    password="123456",
    interval=5,
    qbt=True,
    credentials=True)

For qbt=True/False and credentials=True/False:

Perhaps if you are using MMqBt in another script, you do not want MMqBt to display the option to start qBittorrent (qbt) or the login credentials (credentials).

Notes

Only compatible with macOS due to use of rumps for menu bar integration.

Tested with Python 3.8+ and qBittorrent Web UI 5.x.

Requires qBittorrent Web UI to be enabled and accessible.

Disclaimer

This tool only displays torrent information; it does not modify or control qBittorrent.

Contributing

Feel free to open issues or submit pull requests!

Another qBittorrent plugin

• TrackersRemover-qBittorent: as expected