This guide walks you through every step needed to get Simple Discord Music Bot running on your local machine: cloning the repository, setting up a Python environment, configuring your bot token, launching the Lavalink audio server, and testing playback in a Discord server. The whole process takes under ten minutes if you already have Docker and Python installed.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/DJERLO/Simple-Discord-Music-Bot-Using-Nextcord/llms.txt
Use this file to discover all available pages before exploring further.
Lavalink must be running before you start
bot.py. The bot connects to the Lavalink node during its on_ready event — if the node is unreachable at startup, the bot will fail to initialize audio playback.Prerequisites
Make sure the following are installed and available in your
PATH before continuing:- Python 3.8 or later — the bot uses
asynciofeatures and f-string syntax available from 3.8 onward - Docker (with
docker compose) — used to run the Lavalink audio server - Git — to clone the repository
- A Discord Bot Token — create an application and bot user at the Discord Developer Portal, then copy the token from the Bot tab
If you haven’t set up a Discord application before, enable the Message Content Intent under Bot → Privileged Gateway Intents in the Developer Portal. The bot enables this intent in code, and Discord requires you to opt in on the portal side as well.
Create and Activate a Virtual Environment
Using a virtual environment keeps the bot’s dependencies isolated from your system Python installation.First, create the environment:Then activate it for your operating system:Your terminal prompt should now show
- Windows
- macOS
- Linux
(venv) to confirm the environment is active.Install Dependencies
Install all required Python packages from This installs the following packages:
requirements.txt:| Package | Purpose |
|---|---|
nextcord | Discord API wrapper for Python |
nextcord[voice] | Adds voice connection support to Nextcord |
python-dotenv | Loads environment variables from .env |
wavelink | Async Lavalink client for audio control |
pytest | Test runner for the project’s test suite |
pytest-asyncio | Async support for pytest (used by Discord command tests) |
pytest-watch | File watcher that re-runs tests on save |
Create the .env File
The bot reads your Discord bot token from a Replace
.env file in the project root. Create the file now:your_discord_bot_token_here with the actual token you copied from the Discord Developer Portal.Never commit the
.env file to version control. It is already listed in .gitignore for your protection — do not remove it from that list.Start the Lavalink Server with Docker
The bot streams audio through Lavalink, which runs as a Docker container. Start it in the background with:This pulls the official You should see a container named
ghcr.io/lavalink-devs/lavalink:4.2.2 image, mounts your local application.yml as its configuration file, and exposes port 2333 so the bot can connect. The unless-stopped restart policy means Lavalink will come back up automatically after a system reboot.Confirm it is running:lavalink_node with status Up.Run the Bot
With Lavalink running and your On startup the bot will:
.env file in place, start the bot:- Load
BOT_TOKENfrom.env - Connect to the Lavalink node at
http://127.0.0.1:2333 - Sync all slash commands with Discord
- Log in and display its tag in the terminal
Test Playback in Discord
- Open Discord and join a voice channel in a server where your bot has been invited
- In any text channel, type
/playand enter a song name or YouTube URL when prompted - The bot will join your voice channel, post an “Added to Queue” embed, and begin streaming the track
- A Now Playing embed will appear in the channel and the bot’s status will update to reflect the current track
/queue to see the paginated queue browser, /pause and /resume to control playback, and /skip to move to the next song.