What plugins do and how to add them

qBittorrent plugins let you search for torrents without leaving the application. Instead of opening a web browser and visiting torrent sites separately, you install a plugin that connects qBittorrent directly to search engines and torrent directories. When you search within qBittorrent, it queries those sites and shows results in a list you can download from immediately.

Plugins are small files that qBittorrent reads when it starts. Each plugin contains instructions for how to format a search request to a specific torrent site and how to read the results that come back. Adding plugins means downloading these files and placing them in the folder where qBittorrent looks for them.

The process takes about five minutes and requires no technical knowledge beyond finding a folder and moving files into it. You do not need to restart qBittorrent after adding most plugins — the application finds them the next time you open the search tab.

Key Takeaways

  • Plugins are small files you download and place in qBittorrent's search plugin folder, which you can find through the application's settings menu.
  • The most common source for plugins is the official qBittorrent GitHub repository, which hosts plugins maintained by the qBittorrent community.
  • You can add plugins one at a time by downloading individual files, or download a collection of multiple plugins at once.
  • After placing plugin files in the correct folder, you may need to restart qBittorrent or refresh the search tab to see them appear in your search engine list.
  • Plugin compatibility depends on whether the torrent site is still active and whether the plugin code matches the site's current structure.

Finding and downloading plugins from GitHub

The official qBittorrent search plugins repository is hosted on GitHub at github.com/qbittorrent/search-plugins. This is where the qBittorrent project maintains a collection of plugins that community members have written and tested. You can browse the list of available plugins directly on the website without needing a GitHub account.

On the GitHub page, you will see a folder called nova3 (or nova depending on your qBittorrent version). Inside that folder is a list of plugin files, each one named after a torrent site — for example, piratebay.py, 1337x.py, or kickasstorrents.py. Click on any plugin file to view its contents, then look for a button labeled Raw or a download icon. Right-click that button and select Save link as to download the file to your computer.

Alternatively, you can download all plugins at once by clicking the green Code button near the top of the GitHub page and selecting Download ZIP. This downloads the entire repository as a compressed folder. Extract the ZIP file, navigate to the nova3 folder inside, and you will see all available plugin files ready to move into qBittorrent.

Locating qBittorrent's plugin folder

Before you can add plugins, you need to find where qBittorrent stores them. The location varies depending on your operating system. The easiest way to find it is through qBittorrent itself: open the application, click Tools in the menu bar, then select Options (or Preferences on Mac). In the left sidebar, click Search.

In the Search settings window, you will see a section labeled Search plugins with a folder path displayed. On Windows, this is typically C:\Users\[YourUsername]\AppData\Local\qBittorrent\search_plugins. On Mac, it is usually ~/Library/Application Support/qBittorrent/search_plugins. On Linux, it is often ~/.local/share/qBittorrent/search_plugins or ~/.config/qBittorrent/search_plugins. Click the folder icon next to the path to open it directly in your file manager.

If the search_plugins folder does not exist yet, you can create it manually. Navigate to the parent directory shown in qBittorrent's settings, right-click in the empty space, select New Folder, and name it search_plugins. qBittorrent will recognize it the next time you restart the application.

Moving plugin files into the correct location

Once you have downloaded the plugin files and located the search_plugins folder, the installation is straightforward: move or copy the .py files into that folder. You can do this by dragging and dropping the files from your Downloads folder into the search_plugins folder, or by right-clicking the files, selecting Cut or Copy, navigating to the search_plugins folder, and selecting Paste.

Only move the actual plugin files — the ones with names like piratebay.py or 1337x.py. If you downloaded a ZIP file and extracted it, you will see folders and other files. Navigate into the nova3 folder first, then select only the .py files and move those into qBittorrent's search_plugins folder.

You do not need to restart qBittorrent after adding plugins in most cases. Open the Search tab in qBittorrent, and the new plugins should appear in the dropdown list of search engines. If they do not show up immediately, close and reopen the Search tab, or restart qBittorrent entirely.

Checking that plugins appear in the search tab

After moving plugin files into the search_plugins folder, verify they are working by opening qBittorrent and clicking the Search tab at the bottom of the window. You should see a dropdown menu that says All or lists individual search engines. Click the dropdown to see the full list of available plugins.

If a plugin you added does not appear in the list, the most common reason is that the file is in the wrong location. Double-check that you moved the .py files directly into the search_plugins folder, not into a subfolder. Another possibility is that the plugin file is corrupted or incomplete — try downloading it again from GitHub.

If the plugin appears in the list but returns no results when you search, the torrent site it connects to may be offline, blocked in your region, or may have changed its website structure in a way that breaks the plugin. Plugin files are maintained by volunteers and may not be updated immediately when a site changes.

Managing plugins you no longer want

To remove a plugin, open the search_plugins folder, find the .py file for that plugin, and delete it. You do not need to restart qBittorrent — the plugin will disappear from the search engine dropdown the next time you open the Search tab or restart the application.

If you want to temporarily disable a plugin without deleting it, you can rename the file by adding a different extension — for example, change piratebay.py to piratebay.py.disabled. qBittorrent will ignore files that do not end in .py, and you can rename them back later if you want to use them again.

You can also manage plugins through qBittorrent's interface. Go to Tools > Options > Search, and you will see a list of installed plugins with checkboxes next to each one. Unchecking a box disables that plugin without removing the file.

Troubleshooting plugins that do not work

If a plugin is installed but returns errors or no results, start by checking whether the torrent site itself is accessible. Open a web browser and try visiting the site directly. If the site is down or blocked in your region, the plugin will not work either. Some torrent sites change their web addresses frequently, and plugins may not be updated to match.

If the site is accessible but the plugin still fails, the plugin code may be outdated. Check the GitHub repository to see if there is a newer version of the plugin available. Download the updated version, replace the old file in the search_plugins folder, and try searching again.

Some plugins require specific versions of qBittorrent to work correctly. If you are using an older version of qBittorrent, consider updating to the latest release. Go to Help > About to see your current version, then visit qbittorrent.org to download the newest one.

Frequently Asked Questions

Can I add plugins from sources other than GitHub?

Yes, but GitHub is the most reliable source because plugins there are reviewed by the qBittorrent community. If you find plugins elsewhere, make sure they come from a trusted source and verify that the .py file is not corrupted before moving it into your search_plugins folder. Never download plugins from unknown websites.

Do I need to restart qBittorrent after adding a plugin?

Not usually. Most plugins appear in the search engine dropdown immediately after you move them into the search_plugins folder. If a plugin does not show up, try closing and reopening the Search tab. If it still does not appear, restart qBittorrent.

What does it mean if a plugin shows in the list but returns no results?

The torrent site the plugin connects to may be offline, blocked in your location, or may have changed its website structure. Try visiting the site directly in a web browser to confirm it is accessible. If the site is working but the plugin still fails, the plugin code may need updating.

Can I use plugins on qBittorrent for Mac or Linux?

Yes, the process is identical on all operating systems. The only difference is the location of the search_plugins folder, which varies by OS. Use qBittorrent's Tools > Options > Search menu to find the exact path on your system.

Is it safe to add many plugins at once?

Yes, adding multiple plugins does not slow down qBittorrent or create security issues. The plugins only run when you use the search function. You can add as many as you want and disable the ones you do not use through the Tools > Options > Search menu.