Deploy Lavalink via Docker for Your Discord Music Bot

Lavalink is a standalone Java audio server that your bot delegates all audio decoding and streaming work to. Rather than processing audio inside the Python process, the bot sends playback instructions over HTTP to Lavalink, which handles the heavy lifting independently. Docker is the recommended way to run Lavalink — you get a fully reproducible environment without installing Java, managing versions, or touching system dependencies on your host machine.

If you choose to run Lavalink without Docker, it requires Java 17 or higher. The containerised approach below avoids this requirement entirely.

Local FFmpeg is not required. Lavalink handles all audio decoding and processing internally inside its own container.

docker-compose.yml

The project ships with a ready-made docker-compose.yml that pulls the official Lavalink 4.x image and wires up everything the bot expects.

docker-compose.yml

services:
  lavalink:
    image: ghcr.io/lavalink-devs/lavalink:4.2.2 # Uses the stable v4 production release
    container_name: lavalink_node
    restart: unless-stopped
    ports:
      - "2333:2333" # Opens the port so your Python bot can talk to it
    volumes:
      - ./application.yml:/opt/Lavalink/application.yml # Passes your config into the container
    environment:
      - _JAVA_OPTIONS=-Xmx512M # Allocates max 512MB RAM (perfect for a lightweight lofi bot)

Key values to note:

Field	Value	Purpose
`image`	`ghcr.io/lavalink-devs/lavalink:4.2.2`	Pinned stable release
`container_name`	`lavalink_node`	Friendly name for `docker` CLI commands
`restart`	`unless-stopped`	Auto-restarts on crash; stops only on explicit `docker stop`
`ports`	`2333:2333`	Exposes Lavalink’s HTTP API to the host
`_JAVA_OPTIONS`	`-Xmx512M`	Caps JVM heap at 512 MB

application.yml

The volume mount injects application.yml into the container at /opt/Lavalink/application.yml. This file controls Lavalink’s server port, authentication password, enabled audio sources, and logging output.

application.yml

server:
  port: 2333
  address: 0.0.0.0

plugins:
  youtube:
      enabled: true # Enable the new plugin's configuration
      allowSearch: true
      allowDirectVideoIds: true
      allowDirectPlaylistIds: true

lavalink:
  plugins:
    - dependency: "dev.lavalink.youtube:youtube-plugin:1.18.1"
  server:
    password: "youshallnotpass"
    sources:
      youtube: false
      soundcloud: true
      scSearch: true
      local: false
      http: true # Crucial for streaming 24/7 direct audio/mp3 URLs
    bufferDurationMs: 400
    youtubePlaylistLoadLimit: 6
    gc-warnings: true

metrics:
  prometheus:
    enabled: false
    endpoint: /metrics

logging:
  file:
    path: ./logs/lavalink.log
  level:
    root: INFO
    lavalink: INFO

Notable configuration choices:

YouTube plugin (dev.lavalink.youtube:youtube-plugin:1.18.1) — the official plugin replaces the built-in YouTube source; allowSearch, allowDirectVideoIds, and allowDirectPlaylistIds are all enabled.
SoundCloud (soundcloud: true, scSearch: true) — enables SoundCloud playback and search.
HTTP source (http: true) — allows Lavalink to stream direct audio URLs such as .mp3 files.
bufferDurationMs: 400 — sets the audio buffer to 400 ms for smooth playback.
Logging — Lavalink writes INFO-level logs to ./logs/lavalink.log inside the container.

Starting Lavalink

Verify Docker is running

Open a terminal and confirm the Docker daemon is active:

docker info

If Docker is not running, start Docker Desktop (macOS/Windows) or run sudo systemctl start docker (Linux).

Start Lavalink in the background

From the project root (the directory containing docker-compose.yml), run:

docker compose up -d

The -d flag runs the container detached so it continues in the background after you close the terminal.

Verify Lavalink is running

Open http://localhost:2333 in a browser or use curl:

curl http://localhost:2333

Lavalink returns a short HTML or JSON response when it is online. Any response on port 2333 confirms it is healthy.

Inspect the logs (optional)

To follow Lavalink’s output in real time:

docker compose logs lavalink

Add -f to stream logs continuously:

docker compose logs -f lavalink

Stopping Lavalink

To stop and remove the container:

docker compose down

This tears down the container but preserves your application.yml and the logs/ directory on the host.

Common Issues

Port 2333 is already in use

Another process is bound to port 2333. Find and stop it, or change the host-side port in docker-compose.yml:

ports:
  - "2334:2333"  # host port 2334 maps to container port 2333

If you change the port, update bot.py’s on_ready handler to match the new URI (http://127.0.0.1:2334).

Docker is not running

docker compose up will exit immediately with a connection error if the Docker daemon is not active. Start Docker and retry.

Container exits immediately

Run docker compose logs lavalink to read the startup output. A malformed application.yml (incorrect indentation, wrong password format) is the most common cause of an instant exit.

Bot Setup

Configure the Discord application that will connect to this Lavalink node.

Environment Variables

Check the .env values used by the bot when it starts up.

Quickstart

Follow the end-to-end path from setup to first playback.

Configuration

Review the full audio and permission settings used by the bot stack.

Get Started

Music Commands

Utility

Architecture

Setup

Development

Guides

Release Notes

Deploy Lavalink via Docker for Your Discord Music Bot

docker-compose.yml

application.yml

Starting Lavalink

Stopping Lavalink

Common Issues

Bot Setup

Environment Variables

Quickstart

Configuration

​docker-compose.yml

​application.yml

​Starting Lavalink

​Stopping Lavalink

​Common Issues

​Related Topics

Bot Setup

Environment Variables

Quickstart

Configuration

docker-compose.yml

application.yml

Starting Lavalink

Stopping Lavalink

Common Issues

Related Topics