Environment Variables

Environment variables provide a flexible way to configure Lavalink, especially useful for Docker containers, cloud deployments, and CI/CD pipelines.

Naming Convention

Environment variables follow a specific naming pattern based on the application.yml structure:

Convert to Uppercase

All characters are converted to uppercase

Replace Dots with Underscores

Replace . with _

Handle Arrays

For arrays, append the index starting at 0

Examples

server:
  port: 2333

lavalink:
  server:
    password: "youshallnotpass"

Array Example

lavalink:
  plugins:
    - dependency: "com.github.example:plugin1:1.0.0"
      repository: "https://maven.example.com/releases"
    - dependency: "com.github.example:plugin2:2.0.0"
      repository: "https://maven.example.com/releases"

Configuration Priority

Environment variables take precedence over values in the application.yml file. You can use both methods together.

Configuration is loaded in this order (later sources override earlier ones):

Default values
application.yml file
Environment variables

Complete Variable Reference

Server Configuration

SERVER_PORT=2333
SERVER_ADDRESS=0.0.0.0
SERVER_HTTP2_ENABLED=false

Plugin Configuration

# First plugin
LAVALINK_PLUGINS_0_DEPENDENCY="com.github.example:example-plugin:1.0.0"
LAVALINK_PLUGINS_0_REPOSITORY="https://maven.example.com/releases"
LAVALINK_PLUGINS_0_SNAPSHOT=false

# Second plugin
LAVALINK_PLUGINS_1_DEPENDENCY="com.github.another:another-plugin:2.0.0"
LAVALINK_PLUGINS_1_REPOSITORY="https://maven.example.com/releases"

# Plugin directories and repositories
LAVALINK_PLUGINS_DIR="./plugins"
LAVALINK_DEFAULT_PLUGIN_REPOSITORY="https://maven.lavalink.dev/releases"
LAVALINK_DEFAULT_PLUGIN_SNAPSHOT_REPOSITORY="https://maven.lavalink.dev/snapshots"

Lavalink Server Configuration

# Authentication
LAVALINK_SERVER_PASSWORD="youshallnotpass"

# Audio Sources
LAVALINK_SERVER_SOURCES_YOUTUBE=false
LAVALINK_SERVER_SOURCES_BANDCAMP=true
LAVALINK_SERVER_SOURCES_SOUNDCLOUD=true
LAVALINK_SERVER_SOURCES_TWITCH=true
LAVALINK_SERVER_SOURCES_VIMEO=true
LAVALINK_SERVER_SOURCES_NICO=true
LAVALINK_SERVER_SOURCES_HTTP=true
LAVALINK_SERVER_SOURCES_LOCAL=false

# Audio Filters
LAVALINK_SERVER_FILTERS_VOLUME=true
LAVALINK_SERVER_FILTERS_EQUALIZER=true
LAVALINK_SERVER_FILTERS_KARAOKE=true
LAVALINK_SERVER_FILTERS_TIMESCALE=true
LAVALINK_SERVER_FILTERS_TREMOLO=true
LAVALINK_SERVER_FILTERS_VIBRATO=true
LAVALINK_SERVER_FILTERS_DISTORTION=true
LAVALINK_SERVER_FILTERS_ROTATION=true
LAVALINK_SERVER_FILTERS_CHANNEL_MIX=true
LAVALINK_SERVER_FILTERS_LOW_PASS=true

# Performance Settings
LAVALINK_SERVER_NON_ALLOCATING_FRAME_BUFFER=false
LAVALINK_SERVER_BUFFER_DURATION_MS=400
LAVALINK_SERVER_FRAME_BUFFER_DURATION_MS=5000
LAVALINK_SERVER_OPUS_ENCODING_QUALITY=10
LAVALINK_SERVER_RESAMPLING_QUALITY=LOW
LAVALINK_SERVER_TRACK_STUCK_THRESHOLD_MS=10000
LAVALINK_SERVER_USE_SEEK_GHOSTING=true

# Playlist and Search
LAVALINK_SERVER_PLAYER_UPDATE_INTERVAL=5
LAVALINK_SERVER_YOUTUBE_PLAYLIST_LOAD_LIMIT=6
LAVALINK_SERVER_YOUTUBE_SEARCH_ENABLED=true
LAVALINK_SERVER_SOUNDCLOUD_SEARCH_ENABLED=true
LAVALINK_SERVER_SOUNDCLOUD_FILTER_OUT_PREVIEW_TRACKS=false

# Garbage Collection
LAVALINK_SERVER_GC_WARNINGS=true

# Rate Limiting
LAVALINK_SERVER_RATELIMIT_IP_BLOCKS=["1.0.0.0/8"]
LAVALINK_SERVER_RATELIMIT_EXCLUDE_IPS=[]
LAVALINK_SERVER_RATELIMIT_STRATEGY=RotateOnBan
LAVALINK_SERVER_RATELIMIT_SEARCH_TRIGGERS_FAIL=true
LAVALINK_SERVER_RATELIMIT_RETRY_LIMIT=-1

# YouTube Configuration
LAVALINK_SERVER_YOUTUBE_CONFIG_EMAIL=""
LAVALINK_SERVER_YOUTUBE_CONFIG_PASSWORD=""

# HTTP Proxy Configuration
LAVALINK_SERVER_HTTP_CONFIG_PROXY_HOST="localhost"
LAVALINK_SERVER_HTTP_CONFIG_PROXY_PORT=3128
LAVALINK_SERVER_HTTP_CONFIG_PROXY_USER=""
LAVALINK_SERVER_HTTP_CONFIG_PROXY_PASSWORD=""

# Timeouts
LAVALINK_SERVER_TIMEOUTS_CONNECT_TIMEOUT_MS=3000
LAVALINK_SERVER_TIMEOUTS_CONNECTION_REQUEST_TIMEOUT_MS=3000
LAVALINK_SERVER_TIMEOUTS_SOCKET_TIMEOUT_MS=3000

Metrics Configuration

METRICS_PROMETHEUS_ENABLED=false
METRICS_PROMETHEUS_ENDPOINT=/metrics

Sentry Configuration

SENTRY_DSN=""
SENTRY_ENVIRONMENT="production"
SENTRY_TAGS_SOME_KEY=some_value
SENTRY_TAGS_ANOTHER_KEY=another_value

Logging Configuration

# File and Levels
LOGGING_FILE_PATH=./logs/
LOGGING_LEVEL_ROOT=INFO
LOGGING_LEVEL_LAVALINK=INFO

# Request Logging
LOGGING_REQUEST_ENABLED=true
LOGGING_REQUEST_INCLUDE_CLIENT_INFO=true
LOGGING_REQUEST_INCLUDE_HEADERS=false
LOGGING_REQUEST_INCLUDE_QUERY_STRING=true
LOGGING_REQUEST_INCLUDE_PAYLOAD=true
LOGGING_REQUEST_MAX_PAYLOAD_LENGTH=10000
LOGGING_REQUEST_BEFORE_REQUEST=false

# Log Rotation
LOGGING_LOGBACK_ROLLINGPOLICY_MAX_FILE_SIZE=1GB
LOGGING_LOGBACK_ROLLINGPOLICY_MAX_HISTORY=30

Docker Examples

Docker Compose
Docker Run
.env File

docker-compose.yml

version: '3.8'

services:
  lavalink:
    image: ghcr.io/lavalink-devs/lavalink:latest
    container_name: lavalink
    restart: unless-stopped
    environment:
      - SERVER_PORT=2333
      - SERVER_ADDRESS=0.0.0.0
      - LAVALINK_SERVER_PASSWORD=youshallnotpass
      - LAVALINK_SERVER_SOURCES_YOUTUBE=false
      - LAVALINK_SERVER_SOURCES_BANDCAMP=true
      - LAVALINK_SERVER_SOURCES_SOUNDCLOUD=true
      - LAVALINK_SERVER_SOURCES_HTTP=false
      - LOGGING_LEVEL_ROOT=INFO
      - LOGGING_LEVEL_LAVALINK=INFO
    ports:
      - "2333:2333"
    volumes:
      - ./logs:/opt/Lavalink/logs

docker run -d \
  --name lavalink \
  -p 2333:2333 \
  -e SERVER_PORT=2333 \
  -e SERVER_ADDRESS=0.0.0.0 \
  -e LAVALINK_SERVER_PASSWORD=youshallnotpass \
  -e LAVALINK_SERVER_SOURCES_YOUTUBE=false \
  -e LAVALINK_SERVER_SOURCES_BANDCAMP=true \
  -e LAVALINK_SERVER_SOURCES_SOUNDCLOUD=true \
  -v ./logs:/opt/Lavalink/logs \
  ghcr.io/lavalink-devs/lavalink:latest

Create a .env file:

.env

SERVER_PORT=2333
SERVER_ADDRESS=0.0.0.0

LAVALINK_SERVER_PASSWORD=youshallnotpass

LAVALINK_SERVER_SOURCES_YOUTUBE=false
LAVALINK_SERVER_SOURCES_BANDCAMP=true
LAVALINK_SERVER_SOURCES_SOUNDCLOUD=true
LAVALINK_SERVER_SOURCES_TWITCH=true
LAVALINK_SERVER_SOURCES_VIMEO=true
LAVALINK_SERVER_SOURCES_HTTP=false

LOGGING_LEVEL_ROOT=INFO
LOGGING_LEVEL_LAVALINK=INFO

Reference in docker-compose.yml:

docker-compose.yml

version: '3.8'

services:
  lavalink:
    image: ghcr.io/lavalink-devs/lavalink:latest
    env_file:
      - .env
    ports:
      - "2333:2333"

Shell Examples

Bash/Zsh
PowerShell
CMD

# Export environment variables
export SERVER_PORT=2333
export SERVER_ADDRESS=0.0.0.0
export LAVALINK_SERVER_PASSWORD="youshallnotpass"
export LAVALINK_SERVER_SOURCES_YOUTUBE=false
export LAVALINK_SERVER_SOURCES_BANDCAMP=true

# Run Lavalink
java -jar Lavalink.jar

# Set environment variables
$env:SERVER_PORT = "2333"
$env:SERVER_ADDRESS = "0.0.0.0"
$env:LAVALINK_SERVER_PASSWORD = "youshallnotpass"
$env:LAVALINK_SERVER_SOURCES_YOUTUBE = "false"
$env:LAVALINK_SERVER_SOURCES_BANDCAMP = "true"

# Run Lavalink
java -jar Lavalink.jar

REM Set environment variables
set SERVER_PORT=2333
set SERVER_ADDRESS=0.0.0.0
set LAVALINK_SERVER_PASSWORD=youshallnotpass
set LAVALINK_SERVER_SOURCES_YOUTUBE=false
set LAVALINK_SERVER_SOURCES_BANDCAMP=true

REM Run Lavalink
java -jar Lavalink.jar

Kubernetes Example

deployment.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: lavalink-config
data:
  SERVER_PORT: "2333"
  SERVER_ADDRESS: "0.0.0.0"
  LAVALINK_SERVER_SOURCES_YOUTUBE: "false"
  LAVALINK_SERVER_SOURCES_BANDCAMP: "true"
  LAVALINK_SERVER_SOURCES_SOUNDCLOUD: "true"
  LOGGING_LEVEL_ROOT: "INFO"
---
apiVersion: v1
kind: Secret
metadata:
  name: lavalink-secret
type: Opaque
stringData:
  LAVALINK_SERVER_PASSWORD: "youshallnotpass"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: lavalink
spec:
  replicas: 1
  selector:
    matchLabels:
      app: lavalink
  template:
    metadata:
      labels:
        app: lavalink
    spec:
      containers:
      - name: lavalink
        image: ghcr.io/lavalink-devs/lavalink:latest
        ports:
        - containerPort: 2333
        envFrom:
        - configMapRef:
            name: lavalink-config
        - secretRef:
            name: lavalink-secret

Best Practices

Security

Store sensitive values (passwords, tokens) in secure secret management systems
Use .env files for local development (add to .gitignore)
Never commit secrets to version control
Use Kubernetes Secrets or similar for production deployments

Organization

Group related variables together
Use consistent naming conventions
Document any non-obvious configurations
Keep a reference application.yml file for documentation

Validation

Test configuration changes in a development environment first
Validate boolean values are lowercase (true/false)
Check array indices start at 0 and are sequential
Ensure port numbers are within valid ranges

Performance

Only override values that differ from defaults
Avoid setting every possible variable
Use configuration files for complex nested structures
Consider Config Server for managing multiple instances

Troubleshooting

Variable Not Taking Effect

Check:

Variable name is exactly correct (case-sensitive)
No typos in the variable name
Environment variable is set before starting Lavalink
No application.yml file overriding the value (environment variables have priority)

Boolean Values Not Working

Use lowercase true and false:

# Correct
LAVALINK_SERVER_SOURCES_YOUTUBE=false

# Incorrect
LAVALINK_SERVER_SOURCES_YOUTUBE=False
LAVALINK_SERVER_SOURCES_YOUTUBE=FALSE

Array Configuration Issues

Ensure indices are:

Starting at 0
Sequential (no gaps)
Consistent across related properties

# Correct
LAVALINK_PLUGINS_0_DEPENDENCY="..."
LAVALINK_PLUGINS_0_REPOSITORY="..."
LAVALINK_PLUGINS_1_DEPENDENCY="..."

# Incorrect - skipped index 0
LAVALINK_PLUGINS_1_DEPENDENCY="..."

application.yml Reference

Complete configuration file reference

Config Server

Centralized configuration management

Get Started

Configuration

Clients & Plugins

Environment Variables

Naming Convention

Examples

Array Example

Configuration Priority

Complete Variable Reference

Server Configuration

Plugin Configuration

Lavalink Server Configuration

Metrics Configuration

Sentry Configuration

Logging Configuration

Docker Examples

Shell Examples

Kubernetes Example

Best Practices

Troubleshooting

application.yml Reference

Config Server

Build docs developers (and LLMs) love

Get Started

Configuration

Clients & Plugins

​Naming Convention

​Examples

​Array Example

​Configuration Priority

​Complete Variable Reference

​Server Configuration

​Plugin Configuration

​Lavalink Server Configuration

​Metrics Configuration

​Sentry Configuration

​Logging Configuration

​Docker Examples

​Shell Examples

​Kubernetes Example

​Best Practices

​Troubleshooting

​Related Resources

application.yml Reference

Config Server

Build docs developers (and LLMs) love

Naming Convention

Examples

Array Example

Configuration Priority

Complete Variable Reference

Server Configuration

Plugin Configuration

Lavalink Server Configuration

Metrics Configuration

Sentry Configuration

Logging Configuration

Docker Examples

Shell Examples

Kubernetes Example

Best Practices

Troubleshooting

Related Resources