Skip to content
Get packs

Guide · Open source

How to use pear-desktop: install, themes and plugins

Updated · written with AI from the project's own documentation and checked against our catalogue data

Pear Desktop is a free, MIT-licensed desktop app that wraps YouTube Music in its own window, so it behaves like a regular program instead of a browser tab. It is built with Electron and TypeScript and is aimed at people who want a standalone player window, custom CSS themes, or a way to write their own plugins. This guide covers installing it on macOS, Windows and Arch Linux, loading themes, and a quick overview of plugin development.

Pear Desktoppear-devs/pear-desktop · ★ 34k · MIT

Quick start

  1. 1Pick your install method. Choose Homebrew on macOS, Winget on Windows, or the AUR on Arch Linux. Scoop and eopkg are also listed in the README.
  2. 2Run the install command. Paste the command for your system into a terminal. Use the Winget or Homebrew line exactly as shown in the README.
  3. 3Handle macOS or Windows warnings. If macOS reports the app is damaged, run the xattr command from the README. If SmartScreen blocks the installer, the README notes this is common for unknown publishers.
  4. 4Open the app and find Themes. Launch Pear Desktop, then go to Options, Visual Tweaks, Themes.
  5. 5Load a CSS theme. Select a CSS file to change the look of the player. You can find predefined themes in the linked themes repository.
  6. 6Try a plugin (optional). If you develop, create a folder under src/plugins and an index.ts file that uses createPlugin.

What Pear Desktop is and who it suits

Pear Desktop wraps YouTube Music in a desktop window. The project describes itself as an independent, non-profit, unofficial extension developed by volunteers. It is not affiliated with, authorized by, or endorsed by Google or YouTube.

It suits people who want YouTube Music in a standalone window, users who want to restyle the player with CSS, and developers who want to write plugins. It is less suitable for anyone who needs an official client or who expects an offline music library, since the README does not describe one.

  • Good fit: standalone window, CSS themes, plugin development
  • Poor fit: an official YouTube Music client, or a local offline library with no YouTube Music account

Install Pear Desktop on macOS, Windows or Arch Linux

The simplest route depends on your system. On macOS you can use Homebrew. On Windows you can use Winget, which the README describes as Windows 11's official CLI package manager. On Arch Linux, install the pear-desktop package from the AUR. The README also lists Scoop for Windows and Solus via eopkg.

If you install the macOS app manually and see an error saying it is damaged and can't be opened, the README suggests running the xattr command below in Terminal. Microsoft Defender SmartScreen may block the Windows installer because the publisher is unknown.

  • macOS: brew install pear-devs/pear/pear-desktop
  • Windows: winget install pear-devs.pear-desktop
  • Arch Linux: install the pear-desktop package from the AUR
  • Solus: sudo eopkg install pear-desktop
brew install pear-devs/pear/pear-desktop

Install without a network connection on Windows

The README describes an offline route. Download the nsis.7z file for your architecture from the release page, plus the Setup.exe installer, and place them in the same directory before running the installer.

  • x64 for 64-bit Windows
  • ia32 for 32-bit Windows
  • arm64 for ARM64 Windows

Change the look with CSS themes

You can load CSS files to change how the application looks. In the app, go to Options, then Visual Tweaks, then Themes. The README also links to a set of predefined themes maintained in a separate repository.

  • Open Options > Visual Tweaks > Themes
  • Load a CSS file

Write a plugin (for developers)

Plugins can manipulate the app, since the Electron BrowserWindow is passed to the plugin handler, and they can change the front end by editing HTML and CSS. To create one, make a folder under src/plugins/YOUR-PLUGIN-NAME and add an index.ts file as the main entry point. The plugin uses createPlugin with hooks such as backend, renderer, and preload.

For a simple styling plugin, import a style.css file inline and pass it in the stylesheets array. The README notes that setting restartNeeded to true makes the app show a restart dialog after changes.

  • Use createPlugin from @/utils
  • Hooks include backend, renderer, preload, and menu
  • Set restartNeeded: true if the app should prompt for a restart
src/plugins/YOUR-PLUGIN-NAME/index.ts

Build from source (for contributors)

To run the project from source, clone the repository and install dependencies with pnpm using the frozen lockfile, then start the dev command. The README also mentions devcontainers as an alternative, with the caveat that the GUI does not work on at least some Linux hosts.

git clone https://github.com/pear-devs/pear-desktop cd pear-desktop pnpm install --frozen-lockfile pnpm dev

What people use it for

  • Keep YouTube Music in a separate window instead of a browser tab
  • Restyle the player with a downloaded CSS theme
  • Write a small plugin that injects custom CSS into the player
  • Install and update the app through Homebrew, Winget or the AUR

Frequently asked questions

Is Pear Desktop free?

Yes. The repository is licensed under the MIT licence. The project describes itself as non-profit and volunteer-developed.

Is Pear Desktop official?

No. The project states it is an unofficial extension and is not affiliated with, authorized by, or endorsed by Google LLC or YouTube.

How do I install Pear Desktop on Mac?

Run brew install pear-devs/pear/pear-desktop with Homebrew. If the manually installed app reports it is damaged, the README suggests running the xattr command in Terminal.

How do I install Pear Desktop on Windows?

Use winget install pear-devs.pear-desktop. The README also lists Scoop, and an offline method using the nsis.7z file and Setup.exe placed in the same folder.

Does Pear Desktop work without a YouTube Music account?

The README does not describe a standalone offline music library, so it is built around YouTube Music. Check the project page if you need to confirm account requirements.

What are the alternatives to Pear Desktop?

The README lists comparable projects including th-ch/youtube-music, Musicfox, and ytmdesktop. Each suits different needs, so compare them against what you want from a desktop player.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Pear Desktop is a good choice if you want YouTube Music in a standalone window, want to restyle it with CSS, or plan to write plugins. Do not pick it if you need an official client, or if you want a local offline library, since the README does not describe either.

Install options & downloads