Skip to main content

​
Docker Setup

Running Lavalink in Docker containers provides isolation, portability, and easy management. This is the recommended approach for experienced users and production deployments.
Docker images are available on GitHub Container Registry. Older builds (prior to v3.7.4) are available on Docker Hub.

​
Prerequisites

1

Install Docker and Docker Compose

You need both Docker and Docker Compose installed on your system:Verify your installation:
docker --version
docker compose version

​
Docker Image Variants

Lavalink provides three image variants to suit different needs:
VariantDescriptionJava VersionUserGroupImage Tag Example
UbuntuDefault variant, based on Ubuntu18322322ghcr.io/lavalink-devs/lavalink:4
AlpineSmaller image, based on Alpine17322322ghcr.io/lavalink-devs/lavalink:4-alpine
DistrolessMinimal image, based on Distroless176553465534ghcr.io/lavalink-devs/lavalink:4-distroless
The Alpine variant is recommended for most use cases due to its smaller size while maintaining full functionality.

​
Setup with Docker Compose

1

Create compose.yml

Create a compose.yml file in your project directory:
compose.yml
services:
  lavalink:
    # pin the image version to Lavalink v4 and use the alpine variant for a smaller image size
    image: ghcr.io/lavalink-devs/lavalink:4-alpine
    container_name: lavalink
    restart: unless-stopped
    environment:
      # set Java options here (6GB heap size)
      - _JAVA_OPTIONS=-Xmx6G
      # set lavalink server port
      # - SERVER_PORT=2333
      # set password for lavalink
      # - LAVALINK_SERVER_PASSWORD=youshallnotpass
    volumes:
      # mount application.yml from the same directory, if you want to use environment variables remove this line below
      - ./application.yml:/opt/Lavalink/application.yml
      # persist plugins between restarts, make sure to create the folder & set the correct permissions and user/group id mentioned above
      - ./plugins/:/opt/Lavalink/plugins/
    networks:
      - lavalink
    expose:
      # lavalink exposes port 2333 to connect to for other containers (this is for documentation purposes only)
      - 2333
    ports:
      # you only need this if you want to make your lavalink accessible from outside of containers, keep in mind this will expose your lavalink to the internet
      - "2333:2333"
      # if you want to restrict access to localhost only
      # - "127.0.0.1:2333:2333"
networks:
  # create a lavalink network you can add other containers to, to give them access to Lavalink
  lavalink:
    name: lavalink
If you expose port 2333 to the internet, make sure to use a strong password and consider using a firewall or reverse proxy.
2

Configure Lavalink

You have two options for configuration:Option 1: Using application.yml (recommended)Create an application.yml file in the same directory as compose.yml. See the Configuration File documentation for a complete example.Option 2: Using environment variablesUse environment variables in your compose.yml. See the Environment Variables documentation for examples.
If you use environment variables, remove the ./application.yml volume mount from your compose.yml.
3

Create plugins directory

Create a directory for plugins and set the correct permissions:
mkdir -p plugins
chown 322:322 plugins
The user/group ID varies by image variant. Check the table above for the correct IDs.
4

Start Lavalink

Start your Lavalink container:
docker compose up -d
The -d flag runs the container in detached mode (in the background).
5

Verify it's running

Check the container logs:
docker compose logs -f lavalink
You should see output indicating that Lavalink has started successfully.

​
Docker Networking

If your Discord bot also runs in a Docker container, you can connect both containers using Docker networking:
1

Add your bot to the Lavalink network

In your bot’s compose.yml, add the Lavalink network:
services:
  your-bot:
    # ... your bot configuration
    networks:
      - lavalink

networks:
  lavalink:
    external: true
    name: lavalink
2

Connect using the service name

In your bot’s code, use lavalink as the hostname instead of localhost:
const node = {
  host: "lavalink",  // Use the service name
  port: 2333,
  password: "youshallnotpass"
};
Using Docker networking keeps traffic between containers internal and doesn’t require exposing ports to the host.

​
Managing Your Container

​
View logs

docker compose logs -f lavalink

docker compose restart lavalink

docker compose stop lavalink

docker compose pull lavalink
docker compose up -d lavalink

​
Remove the container

docker compose down

​
Memory Configuration

Adjust the Java heap size using the _JAVA_OPTIONS environment variable: 
environment:
  - _JAVA_OPTIONS=-Xmx2G  # Allocate 2GB
Recommended memory allocation:
  • Small bot (< 10 servers): 1GB - 2GB
  • Medium bot (10-100 servers): 2GB - 4GB
  • Large bot (100+ servers): 4GB - 8GB+

​
Advanced Configuration

​
Using a reverse proxy

If you’re using a reverse proxy like Nginx, ensure WebSocket support is properly configured: 
location / {
    proxy_pass http://lavalink:2333;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $host;
}

​
Custom Docker run command

If you prefer using docker run instead of Docker Compose: 
docker run -d \
  --name lavalink \
  --restart unless-stopped \
  -p 2333:2333 \
  -v ./application.yml:/opt/Lavalink/application.yml \
  -v ./plugins:/opt/Lavalink/plugins \
  -e _JAVA_OPTIONS=-Xmx4G \
  ghcr.io/lavalink-devs/lavalink:4-alpine

​
Next Steps

Configuration

Learn how to configure sources, plugins, and advanced settings

Troubleshooting

Having issues? Check our troubleshooting guide

Plugins

Discover available plugins to extend functionality

Docker Networking

Learn more about Docker networking

Build docs developers (and LLMs) love

Get started for freeTalk to us