How to set up a Lavalink server

What Lavalink does

Lavalink is a standalone audio server for Discord bots. Your bot tells it what to play, and Lavalink loads the track, decodes it and streams it to the voice channel. Moving that work out of the bot keeps it light, and it means one node can serve audio for many bots or shards.

You need a server with Java 17 or newer, a bot, and a Lavalink client library for your bot’s language.

Install Lavalink

Check your Java version, then create a folder for Lavalink:

java -version
mkdir ~/lavalink && cd ~/lavalink

Download the latest Lavalink.jar from the Lavalink releases page into that folder.

Write application.yml

Lavalink reads its settings from application.yml, in the same folder as the jar. This is a working starting point:

server:
  port: 2333
  address: 0.0.0.0

lavalink:
  plugins:
    # Replace VERSION with the current release of youtube-source.
    - dependency: "dev.lavalink.youtube:youtube-plugin:VERSION"
      snapshot: false
  server:
    password: "use-a-long-random-password"
    sources:
      youtube: false

plugins:
  youtube:
    enabled: true
    allowSearch: true
    clients:
      - MUSIC
      - ANDROID_VR
      - WEB
      - WEBEMBEDDED

Two things matter here:

• Change the password. The documentation’s example password is public, so a node left on it can be used by anyone who finds it.
• YouTube comes from a plugin. The built-in source is deprecated, so it is set to false and the youtube-source plugin takes over. Replace VERSION with its latest release, and update it when tracks stop loading.

The Lavalink configuration page lists every other option, including the other audio sources.

Start it and test it

Start Lavalink with a memory limit a little below what the server has. The number after -Xmx is the limit:

java -Xmx1G -jar Lavalink.jar

In another terminal, ask the node for its version, using your own password and address:

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

A version number means the node is up. To keep it running after you log out, use systemd:

[Unit]
Description=Lavalink
After=network-online.target

[Service]
User=lavalink
WorkingDirectory=/home/lavalink/lavalink
ExecStart=/usr/bin/java -Xmx1G -jar /home/lavalink/lavalink/Lavalink.jar
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

Save that as /etc/systemd/system/lavalink.service, then run sudo systemctl daemon-reload and sudo systemctl enable --now lavalink.

Connect your bot

Your bot needs a client library, and each one asks for the same three things: the node’s address, port and password. Use the plain ws and http scheme unless you have put TLS in front of the node.

The Lavalink clients page has the full list and shows which clients are no longer maintained, so check it before you pick one.

Lock it down

If your bot runs on a different server, allow only that server to reach the port, so the node is not open to the whole internet. With ufw:

sudo ufw allow from YOUR_BOT_IP to any port 2333 proto tcp

If the bot runs on the same machine, set address: 127.0.0.1 and open nothing at all.

How much memory does Lavalink need?

It depends on how many players run at once and whether they use filters. These are the sizes we suggest for our own Lavalink plans:

A free public node saves the cost, but it is shared with strangers and can vanish without warning. If people rely on your bot, give it a node of its own.

Common problems

• Unauthorized or 401: the password in your bot does not match application.yml.
• Connection refused: Lavalink is not running, or a firewall or the wrong address is in the way.
• UnsupportedClassVersionError: Java is older than 17, so update it.
• YouTube tracks fail to load: update the youtube-source plugin to its latest release.
• No sound but no errors: update your client library, since Discord’s voice protocol changes too.