Registry / http-networking / red-lavalink

red-lavalink

JSON →
library0.11.1pypypi✓ verified 24d ago

Red-Lavalink is a client library for the Lavalink audio server, specifically designed for use with Red-DiscordBot but usable in other `discord.py` projects. It enables advanced audio playback features for Discord bots, allowing them to connect to Lavalink nodes for powerful music and audio streaming capabilities. The library is actively maintained, with regular updates to support new `discord.py` versions and Lavalink protocol changes. The current stable version is 0.11.1.

pip install red-lavalink
INSTALL
IMPORT
SIG · RED-LAVALINK
R
red-lavalink
http-networkingpythonv0.11.1
Install
4.5s avg
Import
873ms
Disk
35MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.904s · 34.5MB
glibc
py 3.103.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)
Debug
Known issues
breakingVersion 0.11.0 dropped support for `discord.py` 1.x. Users must upgrade their `discord.py` installation to version 2.0.0a+ or newer.
fix
Upgrade `discord.py` to `discord.py>=2.0.0a3020050800` (or the latest stable `discord.py v2` version).
affects: >=0.11.0
breakingVersion 0.11.0 introduced significant breaking changes to the internal API due to a switch to `discord.py`'s `VoiceProtocol`. This includes removal of `user_id`, `PlayerManager`, `enums.DiscordVoiceSocketResponses`, renaming of `lavalink.player_manager` module to `lavalink.player`, and removal of methods like `Player.manager`, `Node.player_manager`, `Node.get_voice_ws()`, and `Node.join_voice_channel()`.
fix
Refer to the `red-lavalink` 0.11.0 documentation or examples for updated usage patterns, particularly around voice connection and player management. The `lavalink.connect()` function should now be used to join voice channels.
affects: >=0.11.0
breakingThe `secured` parameter in `Node.connect()` was removed in version 0.10.0. Secure WebSocket connections are now handled automatically based on the port and host settings.
fix
Remove the `secured` parameter from any calls to `Node.connect()`.
affects: >=0.10.0
gotchaAs of `red-lavalink` 0.11.1, the library sends the voice channel ID to the Lavalink server, which is required by newer Lavalink server versions to support Discord's DAVE protocol. Ensure your Lavalink server is also up-to-date to fully utilize this.
fix
While `red-lavalink` handles this on the client side, ensure your deployed Lavalink Java server is running a recent version that supports the DAVE protocol for optimal compatibility.
affects: >=0.11.1
gotchaThe `ExceptionSeverity` enum value `FATAL` was renamed to `FAULT` in version 0.10.0 to align with Lavalink's API.
fix
Update any code referencing `ExceptionSeverity.FATAL` to `ExceptionSeverity.FAULT`.
affects: >=0.10.0
gotchaRed-Lavalink requires a separate, running Lavalink Java server. For standalone projects, you must deploy and manage a Lavalink server instance. As of recent Red-DiscordBot updates (3.5.23/24), Lavalink servers typically require Java 17 or newer.
fix
Set up and run a Lavalink Java server (e.g., from `https://github.com/Cog-Creators/Lavalink-Jars` or `https://github.com/Lavalink-Devs/Lavalink/`). Ensure it's running on Java 17+.
affects: all
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`.
fix
Ensure 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.
fix
Verify 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`.
fix
Ensure 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.
fix
Ensure 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.
Agent activity
18 hits · last 30 days
node
16
Resources
red-lavalink — pip install red-lavalink · libregistry