Installing addons

Learn how to install plugins and themes to customize your Discord experience

BetterDiscord allows you to install addons—plugins and themes—to customize your Discord client. This guide will walk you through the installation process.

What are addons?

Addons are custom modifications that extend BetterDiscord’s functionality:

• Plugins (.plugin.js) - Add new features and functionality to Discord
• Themes (.theme.css) - Change Discord’s appearance with custom styles

Installing addons

1. Open your addons folder

   You can access your addons folder in several ways:

   • Open Discord settings and navigate to the Plugins or Themes tab
   • Click the Open Folder button at the top of the page

   Alternatively, you can navigate directly to:

   • Windows: %appdata%/BetterDiscord/plugins or %appdata%/BetterDiscord/themes
   • macOS: ~/Library/Application Support/BetterDiscord/plugins or ~/Library/Application Support/BetterDiscord/themes
   • Linux: ~/.config/BetterDiscord/plugins or ~/.config/BetterDiscord/themes
2. Download an addon

   Visit the BetterDiscord website to browse and download addons:

   • Browse the plugins or themes library
   • Click on an addon to view its details
   • Click the Download button

   Make sure you’re downloading from trusted sources. All addons on the official BetterDiscord website are reviewed for safety.

3. Move the file to your addons folder

   After downloading:

   1. Locate the downloaded file (it should end in .plugin.js or .theme.css)
   2. Move or copy the file into the appropriate folder:
      • Plugins go in the plugins folder
      • Themes go in the themes folder

   If your browser added a .txt extension or changed the file extension, make sure to rename it back to .plugin.js or .theme.css.

4. Enable the addon

   The addon should now appear in BetterDiscord:

   1. Open Discord settings
   2. Navigate to Plugins or Themes (under the BetterDiscord section)
   3. Find your newly installed addon in the list
   4. Toggle it on to enable it

   You should see a success toast notification confirming the addon was enabled.

Auto-loading addons

BetterDiscord automatically watches your addons folders for changes. This means:

• New files added to the folder will be detected and loaded automatically
• Modified files will be reloaded with your changes
• Deleted files will be unloaded from BetterDiscord

You don’t need to restart Discord when adding new addons—they’ll be detected and loaded automatically.

Handling duplicate files

If you download a file with a duplicate name, your browser may append a number to the filename (e.g., theme(1).theme.css). BetterDiscord automatically detects and renames these files to the correct format.

If both the original and duplicate file exist, BetterDiscord will warn you about duplicate files and won’t automatically rename them to avoid conflicts.

File format requirements

Plugins

Plugin files must:

• End with the .plugin.js extension
• Contain a JSDoc comment block at the top with metadata:
  • @name - The plugin name
  • @author - The plugin author
  • @description - A brief description
  • @version - The version number

Themes

Theme files must:

• End with the .theme.css extension
• Contain a JSDoc comment block at the top with metadata (same as plugins)
• Contain valid CSS code

Troubleshooting

If an addon doesn’t appear after installation:

1. Check the file extension - Ensure it ends with .plugin.js or .theme.css
2. Check the file location - Make sure it’s in the correct folder (plugins or themes)
3. Check for errors - Look for error messages in the BetterDiscord console
4. Try reloading Discord - Press Ctrl+R (or Cmd+R on macOS) to reload

For more help, see the troubleshooting guide.