Installation

Install BetterDiscord on Windows, macOS, or Linux using the automatic installer or manual installation method.

BetterDiscord provides automatic installers for all major platforms, making installation quick and easy. For advanced users or when installers don’t work, manual installation is also available.

Automatic installation

The recommended way to install BetterDiscord is using the automatic installer for your operating system.

1. Download the installer

   Download the installer for your operating system:

   Windows

   Windows 7+

   Download installer

   macOS

   macOS 10.10+

   Download installer

   Linux

   Ubuntu 14.04+

   Download installer

2. Run the installer

   Windows

   Double-click the BetterDiscord-Windows.exe file to launch the installer.

   macOS

   Extract the downloaded zip file and run the installer application.

   Linux

   Make the AppImage executable and run it:

   chmod +x BetterDiscord-Linux.AppImage
   ./BetterDiscord-Linux.AppImage
   
3. Select your Discord installation

   The installer will detect your Discord installations. Select the release channel you want to install BetterDiscord to:

   • Stable - The main Discord release
   • PTB - Public Test Build
   • Canary - Experimental features

   You can install BetterDiscord on multiple Discord installations. Just run the installer again and select a different channel.

4. Complete installation

   Click the install button and wait for the process to complete. Once finished, fully restart Discord to activate BetterDiscord.

   You must completely close Discord (not just minimize it) and reopen it for BetterDiscord to load.

5. Verify installation

   After restarting Discord, verify that BetterDiscord is installed:

   1. Look for the BetterDiscord icon in your Discord settings (bottom left)
   2. The settings should now include BetterDiscord sections for Plugins, Themes, and Custom CSS

   If you don’t see BetterDiscord settings after restarting, try repairing your installation by running the installer again.

Manual installation

Manual installation is recommended for developers or when the automatic installer doesn’t work.

Manual installation requires technical knowledge and familiarity with the command line. Most users should use the automatic installer instead.

1. Clone the repository

   Clone the BetterDiscord repository and navigate to it:

   git clone https://github.com/BetterDiscord/BetterDiscord.git
   cd BetterDiscord
   
2. Install dependencies and build

   Install dependencies using pnpm and build the project:

   pnpm install
   pnpm build
   

   This will generate a dist folder with compiled files.

   BetterDiscord uses pnpm as its package manager. Make sure you have it installed before proceeding.

3. Inject into Discord

   Use the built-in injection script to inject BetterDiscord into your desired Discord release channel:

   pnpm inject <channel>
   

   Replace <channel> with one of:

   • stable - Main Discord release
   • canary - Experimental features
   • ptb - Public Test Build

   Example:

   pnpm inject stable
   
4. Restart Discord

   Fully restart Discord for the changes to take effect. BetterDiscord should now be active.

   For development, renderer changes will be picked up on Discord reload (Ctrl+R). Preload and injector changes require a full Discord restart.

Platform-specific notes

Windows

• Windows 7 and newer are supported
• The installer requires administrator privileges
• Windows Defender may show a warning - this is normal for unsigned installers

macOS

• macOS Yosemite (10.10) and newer are supported
• You may need to allow the app in System Preferences > Security & Privacy
• Extract the zip file before running the installer

Linux

• Ubuntu 14.04 and newer are supported
• The AppImage must be made executable before running
• Snap packages are not supported - use standard Discord installation

Troubleshooting

BetterDiscord isn’t showing up

1. Make sure you completely closed and reopened Discord
2. Try repairing your installation by running the installer again
3. Check that you’re using a supported Discord installation (not snap, portable, or web)

Installer won’t run

Windows: Right-click the installer and select “Run as administrator”

macOS: Open System Preferences > Security & Privacy and allow the app to run

Linux: Ensure the AppImage has execute permissions (chmod +x)

Discord updates broke BetterDiscord

When Discord updates, it may overwrite the BetterDiscord injection. Simply run the installer again to repair it.

Join the BetterDiscord Discord server for help with installation issues. Check the #faq and #announcements channels first.

Next steps

Now that BetterDiscord is installed, check out the quick start guide to install your first plugins and themes.