Install & Compatibility
Where this runs
tested against v0.11.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.904s · 34.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.5s · import 0.842s · 37MB
35MB installed
● package 35MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
lavalink
✓ import lavalink
The primary module for interacting with Red-Lavalink functionalities.
This quickstart demonstrates how to set up a basic `discord.py` bot using `red-lavalink` to connect to a Lavalink server, join a voice channel, and play music. It includes commands for joining, playing, and stopping audio. Ensure your `DISCORD_BOT_TOKEN`, `LAVALINK_HOST`, `LAVALINK_PORT`, and `LAVALINK_PASSWORD` are set either as environment variables or replaced directly in the code. A running Lavalink Java server is required.
import lavalink
import os
from discord.ext.commands import Bot, Context
import discord
# Replace with your bot token and Lavalink credentials
BOT_TOKEN = os.environ.get('DISCORD_BOT_TOKEN', 'YOUR_BOT_TOKEN')
LAVALINK_HOST = os.environ.get('LAVALINK_HOST', 'localhost')
LAVALINK_PORT = int(os.environ.get('LAVALINK_PORT', '2333'))
LAVALINK_PASSWORD = os.environ.get('LAVALINK_PASSWORD', 'youshallnotpass')
class MyBot(Bot):
def __init__(self):
super().__init__(command_prefix='!', intents=discord.Intents.default())
async def setup_hook(self):
# Initialize Lavalink AFTER the bot is ready
await lavalink.initialize(
self,
host=LAVALINK_HOST,
password=LAVALINK_PASSWORD,
port=LAVALINK_PORT
)
print(f"Lavalink initialized to {LAVALINK_HOST}:{LAVALINK_PORT}")
async def on_ready(self):
print(f'Logged in as {self.user} (ID: {self.user.id})')
print('------')
async def on_voice_state_update(self, member, before, after):
# Handle disconnects if the bot is alone in a voice channel
if member == self.user and not after.channel:
# Bot disconnected from voice
player = lavalink.get_player(member.guild.id)
if player:
await player.disconnect()
async def on_lavalink_event(self, player, event, extra=None):
print(f"Lavalink Event: {event} for player in guild {player.guild.id}")
@commands.command()
async def join(self, ctx: Context, *, channel: discord.VoiceChannel = None):
"""Joins a voice channel."""
if not channel and not ctx.author.voice:
return await ctx.send("You are not in a voice channel nor specified one.")
channel = channel or ctx.author.voice.channel
player = await lavalink.connect(channel)
await ctx.send(f"Joined {channel.name}")
@commands.command()
async def play(self, ctx: Context, *, query: str):
"""Searches and plays a song."""
player = lavalink.get_player(ctx.guild.id)
if not player or not player.is_connected:
return await ctx.send("I am not connected to a voice channel.")
tracks = await player.search_yt(query)
if not tracks:
return await ctx.send("No tracks found.")
player.add(requester=ctx.author, track=tracks[0])
if not player.is_playing:
await player.play()
await ctx.send(f"Now playing: {tracks[0].title}")
else:
await ctx.send(f"Added to queue: {tracks[0].title}")
@commands.command()
async def stop(self, ctx: Context):
"""Stops playback and clears the queue."""
player = lavalink.get_player(ctx.guild.id)
if not player or not player.is_connected:
return await ctx.send("I am not connected to a voice channel.")
await player.stop()
player.queue.clear()
await ctx.send("Playback stopped and queue cleared.")
bot = MyBot()
bot.run(BOT_TOKEN)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'lavalink'
Developers often confuse the `red-lavalink` library's package name with a generic `lavalink` package and attempt to import `lavalink` directly instead of `red_lavalink`.
fixEnsure you have installed the correct library with `pip install red-lavalink` and use the correct import statement: `from red_lavalink import Lavalink`.
LavalinkNodeError: Could not connect to Lavalink node
The bot failed to establish a connection with the specified Lavalink server, often due to the server not running, incorrect host/port details, invalid credentials, or network/firewall issues.
fixVerify that your Lavalink server is running, its host, port, and password match the configuration provided to `bot.lavalink.add_node()`, and there are no network restrictions preventing the connection.
AttributeError: 'NoneType' object has no attribute 'add_node'
This error occurs when trying to access `bot.lavalink.add_node()` before the `Lavalink` cog has been properly initialized and added to the bot, meaning `bot.lavalink` is still `None`.
fixEnsure that `bot.add_cog(Lavalink(bot))` is called during your bot's setup (e.g., in `setup_hook` or a `setup` function) and that you attempt to add nodes only after the bot is ready and the cog is loaded (e.g., in `on_ready`).
No nodes are available for connection.
The `red-lavalink` client has no active Lavalink nodes configured or successfully connected, preventing it from performing audio operations.
fixEnsure you have called `await bot.lavalink.add_node(host, port, password, region)` with correct credentials after the bot is ready, and that these nodes successfully connected to their respective Lavalink servers.
Upgrade
Version history
0.11.1latest on PyPI · released Mar 3, 2026
Audit
Dependencies
discord.pyrequiredCore dependency for Discord bot integration, specifically requires 2.0.0a+.
aiohttprequiredUsed for underlying HTTP and WebSocket communication with Lavalink.
async_timeoutrequiredUsed for managing connection timeouts.