Skip to main content

​
Systemd Service Setup

Running Lavalink as a systemd service ensures that it starts automatically on boot, restarts on failure, and integrates seamlessly with your Linux system’s service management.
This is the recommended way to run Lavalink on Linux production servers.

​
Prerequisites

1

Verify systemd is available

Ensure your Linux distribution uses systemd:
systemctl --version
You should see version information for systemd.
2

Install Lavalink binary

Follow the Binary Installation guide to download and set up Lavalink before proceeding.Make sure you have:
  • Downloaded Lavalink.jar
  • Created an application.yml configuration file
  • Tested that Lavalink runs correctly

​
Service Configuration

1

Create the systemd service file

Create a new service file at /usr/lib/systemd/system/lavalink.service:
sudo nano /usr/lib/systemd/system/lavalink.service
Add the following configuration, replacing the values in <> brackets with your actual values:
lavalink.service
[Unit]
# Describe the service
Description=Lavalink Service

# Configure service order
After=syslog.target network.target

[Service]
# The user which will run Lavalink
User=<usr>

# The group which will run Lavalink
Group=<usr>

# Where the program should start
WorkingDirectory=</home/usr/lavalink>

# The command to start Lavalink
ExecStart=java -Xmx4G -jar </home/usr/lavalink>/Lavalink.jar

# Restart the service if it crashes
Restart=on-failure

# Delay each restart by 5s
RestartSec=5s

[Install]
# Start this service as part of normal system start-up
WantedBy=multi-user.target
Make sure to replace:
  • <usr> with your actual username (appears twice)
  • </home/usr/lavalink> with the full path to your Lavalink directory (appears twice)
2

Example configuration

Here’s a concrete example for a user named musicbot with Lavalink installed in /home/musicbot/lavalink:
lavalink.service
[Unit]
Description=Lavalink Service
After=syslog.target network.target

[Service]
User=musicbot
Group=musicbot
WorkingDirectory=/home/musicbot/lavalink
ExecStart=java -Xmx4G -jar /home/musicbot/lavalink/Lavalink.jar
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target
3

Reload systemd daemon

After creating the service file, reload systemd to recognize the new service:
sudo systemctl daemon-reload
4

Enable the service

Enable the service to start automatically on boot:
sudo systemctl enable lavalink
You should see output confirming the service has been enabled.
5

Start the service

Start Lavalink:
sudo systemctl start lavalink
6

Verify it's running

Check the service status:
sudo systemctl status lavalink
You should see active (running) in green, indicating that Lavalink is running successfully.

​
Managing the Service

​
Check service status

sudo systemctl status lavalink

​
View logs

sudo journalctl -u lavalink

​
Follow logs in real-time

sudo journalctl -u lavalink -f

​
View recent logs

sudo journalctl -u lavalink -n 100

​
Restart the service

sudo systemctl restart lavalink

​
Stop the service

sudo systemctl stop lavalink

​
Disable auto-start on boot

sudo systemctl disable lavalink

​
Memory Configuration

Adjust the memory allocation in the ExecStart line of your service file: 
ExecStart=java -Xmx2G -jar /home/musicbot/lavalink/Lavalink.jar
Recommended memory allocation:
  • Small bot (< 10 servers): 512MB - 1GB (-Xmx1G)
  • Medium bot (10-100 servers): 1GB - 2GB (-Xmx2G)
  • Large bot (100+ servers): 2GB - 4GB+ (-Xmx4G)
After modifying the service file, run sudo systemctl daemon-reload and sudo systemctl restart lavalink to apply changes.

​
Additional Java Options

You can add additional Java options to optimize performance: 
ExecStart=java -Xmx4G -Xms4G -XX:+UseG1GC -XX:+ParallelRefProcEnabled -jar /home/musicbot/lavalink/Lavalink.jar
Common options:
  • -Xmx4G - Maximum heap size
  • -Xms4G - Initial heap size (matching Xmx reduces garbage collection overhead)
  • -XX:+UseG1GC - Use G1 garbage collector (recommended for most cases)
  • -XX:+ParallelRefProcEnabled - Enable parallel reference processing

​
Troubleshooting

​
Service fails to start

If the service fails to start, check the logs: 
sudo journalctl -u lavalink -n 50
Common issues:
  • Permission denied: Ensure the user specified in the service file has read/execute permissions on Lavalink.jar
  • Java not found: Install Java 17 or higher and ensure it’s in the system PATH
  • Configuration errors: Verify your application.yml is valid

​
Check file permissions

ls -la /home/musicbot/lavalink/
Ensure the user running Lavalink owns the files: 
sudo chown -R musicbot:musicbot /home/musicbot/lavalink/

​
Service keeps restarting

If the service is constantly restarting, there’s likely a configuration error. Check the logs: 
sudo journalctl -u lavalink -f
Look for error messages that indicate what’s causing the crashes.

​
Security Considerations

Never run Lavalink as the root user. Always use a dedicated user account with minimal permissions.

​
Create a dedicated user

It’s best practice to create a dedicated user for running Lavalink: 
sudo useradd -r -s /bin/false lavalink
sudo mkdir -p /opt/lavalink
sudo chown lavalink:lavalink /opt/lavalink
Then update your service file to use this user: 
User=lavalink
Group=lavalink
WorkingDirectory=/opt/lavalink
ExecStart=java -Xmx4G -jar /opt/lavalink/Lavalink.jar

​
Next Steps

Configuration

Learn how to configure sources, plugins, and advanced settings

Troubleshooting

Having issues? Check our troubleshooting guide

Monitoring

Set up monitoring and metrics collection

Clients

Choose a client library to connect your bot to Lavalink

Build docs developers (and LLMs) love

Get started for freeTalk to us