Skip to content

Discord bots

How to set up Lavalink for a Discord music bot

Configure a Lavalink v4 node, add the YouTube plugin and connect your discord.js or Python bot to it.

Lavalink is a standalone audio server for Discord bots. Instead of your bot downloading, decoding and encoding audio itself, it tells Lavalink what to play and Lavalink streams it to Discord. Your bot stays responsive, and one node can serve every server your bot is in. This guide sets up Lavalink v4 and connects a bot to it.

What you need

  • A Lavalink node. Either a hosted Lavalink node, where Java and Lavalink are set up for you, or a VPS where you install it yourself.
  • Java 17 or newer, if you run Lavalink yourself.
  • A bot library with a Lavalink v4 client.

1. Configure application.yml

Lavalink reads its settings from application.yml next to Lavalink.jar. A minimal v4 configuration looks like this:

server:
  port: 2333
  address: 0.0.0.0

lavalink:
  plugins:
    - dependency: "dev.lavalink.youtube:youtube-plugin:VERSION"
      snapshot: false
  server:
    password: "change-this-to-something-long"
    sources:
      youtube: false   # handled by the YouTube plugin instead
      bandcamp: true
      soundcloud: true
      twitch: true
      vimeo: true
      http: true
      local: false

plugins:
  youtube:
    enabled: true

Replace VERSION with the latest release from the YouTube source plugin's GitHub page. In Lavalink v4, YouTube support moved out of Lavalink itself into this plugin, which is why the built-in youtube source is turned off.

2. Choose a strong password

Anyone who knows your node's address and password can play audio through it. Use a long random password, keep it in your bot's environment variables, and don't use the example password from tutorials.

3. Start the node and test it

Start Lavalink with java -jar Lavalink.jar (on a hosted node, just press start). When it's ready, you'll see a message that Lavalink has started. Test it from any computer:

curl -H "Authorization: your-password" http://your-node-host:2333/version

If it returns a version number, the node is reachable and your password is correct.

4. Connect a discord.js bot

There are several Lavalink clients for Node.js, including Shoukaku, lavalink-client, Riffy and Moonlink. With Shoukaku, the connection looks like this:

const { Client, GatewayIntentBits } = require('discord.js');
const { Shoukaku, Connectors } = require('shoukaku');

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

const nodes = [{
    name: 'main',
    url: 'your-node-host:2333',
    auth: process.env.LAVALINK_PASSWORD,
}];

const shoukaku = new Shoukaku(new Connectors.DiscordJS(client), nodes);
shoukaku.on('error', (name, error) => console.error(`Lavalink ${name}:`, error));

client.login(process.env.DISCORD_TOKEN);

Note the GuildVoiceStates intent: without it, your bot can't see which voice channel to join. From here, follow your client's documentation to join a channel, search for tracks and play them.

5. Connect a Python bot

For discord.py, Wavelink is the most popular client. Connect to your node in setup_hook:

import os

import discord
import wavelink
from discord.ext import commands


class MusicBot(commands.Bot):
    async def setup_hook(self):
        node = wavelink.Node(
            uri="http://your-node-host:2333",
            password=os.getenv("LAVALINK_PASSWORD"),
        )
        await wavelink.Pool.connect(nodes=[node], client=self)


intents = discord.Intents.default()
intents.voice_states = True
bot = MusicBot(command_prefix="!", intents=intents)
bot.run(os.getenv("DISCORD_TOKEN"))

Useful plugins

  • LavaSrc adds Spotify, Apple Music and Deezer links. It looks up the track's details and finds a playable version on another source.
  • SponsorBlock skips sponsor segments in videos.
  • LavaSearch adds richer search results such as albums and artists.

Plugins are added to the lavalink.plugins list the same way as the YouTube plugin.

Common problems

  • 401 Unauthorized: the password in your bot doesn't match lavalink.server.password.
  • Connection refused: wrong host or port, or a firewall is blocking it. Check the port in the panel or server.port.
  • Tracks fail to load from YouTube: update the YouTube plugin. YouTube changes often, and the plugin is updated to keep up.
  • Audio stutters: the node is short on CPU or memory, or is far from your bot. Host both in the same location, and upgrade the node if it's busy.

Please respect the terms of the sources you stream from. Our acceptable use policy applies to all audio hosted on our network.

Get a Lavalink node

Lavalink v4 nodes ready to connect, with 50% off, applied automatically, when you host your bot with us too.

Starting at €3.08EUR/mo