Skip to main content

​
Installation

This guide will walk you through installing Discord Player and all the required dependencies.

​
Prerequisites

Discord Player requires Discord.js 14.0 or higher. Please ensure that you have a compatible version before proceeding.
Check your current Discord.js version: 
npm list discord.js
If you’re using an earlier version, update it first. The discord.js Guide provides resources to assist you with the update process.

​
Installation Steps

1

Install Discord Player

Install the main Discord Player library and the extractors package:
npm install discord-player @discord-player/extractor
The @discord-player/extractor package provides default extractors for popular platforms like YouTube, Spotify, SoundCloud, and more.
2

Install Opus Library

We recommend mediaplex for libopus. Mediaplex also helps with audio metadata extraction:
npm install mediaplex
Opus is required for encoding audio data. Without an opus library, Discord Player won’t be able to stream audio to Discord.
3

Install FFmpeg

FFmpeg or Avconv is required for media transcoding. You can install it from the official website or via npm.Download and install FFmpeg from https://ffmpeg.org
We do not recommend installing FFmpeg via npm because binaries pulled from npm are known to be unstable. It is recommended to install it from the official source.

​
Alternative: NPM Installation

If you must install via npm, choose one of these packages:
npm install ffmpeg-static
Use the FFMPEG_PATH environment variable to load FFmpeg from a custom path if needed.
4

Verify Installation

Create a simple script to verify your installation:
verify.js
const { Player } = require('discord-player');
const { Client } = require('discord.js');

const client = new Client({
  intents: ['Guilds', 'GuildVoiceStates'],
});

const player = new Player(client);

console.log(player.scanDeps());
Run the script:
node verify.js
You should see output showing the versions of all installed dependencies:
Discord Player
--------------------------------------------------
- discord-player: 7.2.0
- discord-voip: x.x.x
- discord.js: 14.x.x
- Node version: vx.x.x (Detected Runtime: Node, Platform: ...)
- ffmpeg: x.x.x
- command: ffmpeg
- libopus: true

Loaded Extractors:
--------------------------------------------------
N/A
The extractors list will be empty until you load them in your main application.

​
Optional Dependencies

​
Additional Extractors

While @discord-player/extractor provides most common extractors, you can install additional packages for specific platforms: 
npm install play-dl youtube-sr ytdl-core

​
Custom FFmpeg Path

If you need to specify a custom FFmpeg path, you can do so when creating the Player instance: 
const player = new Player(client, {
  ffmpegPath: '/path/to/ffmpeg',
});
Or set it as an environment variable: 
export FFMPEG_PATH=/path/to/ffmpeg

​
Dependency Overview

Here’s what each dependency does:
PackagePurposeRequired
discord-playerCore frameworkYes
@discord-player/extractorDefault extractors for audio sourcesYes
discord.jsDiscord API wrapperYes
mediaplexOpus encoding/decodingYes
ffmpegAudio/video transcodingYes

​
Troubleshooting

​
FFmpeg Not Found

If you get an error that FFmpeg is not found:
  1. Ensure FFmpeg is installed and available in your system PATH
  2. Try setting the FFMPEG_PATH environment variable
  3. Use the ffmpegPath option when creating the Player instance

​
Opus Library Issues

If you encounter opus-related errors:
  1. Make sure you’ve installed mediaplex
  2. Try reinstalling the package: npm install mediaplex --force
  3. Check that your Node.js version is compatible

​
Discord.js Version Mismatch

If you see warnings about Discord.js version:
  1. Update Discord.js to v14.0 or higher: npm install discord.js@latest
  2. Clear your node_modules and reinstall: rm -rf node_modules && npm install

​
Missing GuildVoiceStates Intent

If voice connections aren’t working: 
const client = new Client({
  intents: [
    'Guilds',
    'GuildVoiceStates', // This is required!
    'GuildMessages',
  ],
});
Without the GuildVoiceStates intent, Discord Player cannot handle voice state updates and won’t be able to connect to voice channels properly.

​
Next Steps

Now that you have Discord Player installed, proceed to the Quick Start guide to create your first music bot!

Build docs developers (and LLMs) love

Get started for freeTalk to us