Skip to main content
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.
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.
1

Prerequisites

Make sure the following are installed and available in your PATH before continuing:
  • Python 3.12 or later — Older versions of Python (like 3.10 or lower) will cause the bot to crash on startup.
  • 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.
2

Clone the Repository

Clone the project from GitHub and navigate into the project directory:
3

Create and activate your environment

The recommended workflow is to use uv, which manages the Python environment and installs dependencies automatically.If you are not using uv, create a virtual environment manually:
Then activate it for your operating system:
Your terminal prompt should now show (venv) to confirm the environment is active.
4

Install uv

Install uv, the recommended Python environment manager for this project.
Verify the install with:
If uv is not on your PATH after installation, add the user scripts directory for your OS or reopen the terminal.
5

Install Dependencies

Install the project dependencies with uv:
This installs the runtime and development dependencies defined in pyproject.toml.
If you need a specific Python version, install it with uv python install 3.13 before uv sync. Then run uv sync again to ensure the project environment is fully configured.
If you prefer a traditional Python environment, create and activate a virtual environment and then install dependencies from requirements.txt:
This project still includes requirements.txt for compatibility, but uv sync is the recommended workflow.
6

Create the .env File

The bot reads your Discord bot token from a .env file in the project root. Create the file now:
Replace 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.
7

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 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:
You should see a container named lavalink_node with status Up.
8

Run the Bot

With Lavalink running and your .env file in place, start the bot:
On startup the bot will:
  1. Load BOT_TOKEN from .env
  2. Connect to the Lavalink node at http://127.0.0.1:2333
  3. Sync all slash commands with Discord
  4. Log in and display its tag in the terminal
You should see no connection errors in the terminal output if Lavalink is healthy.
9

Test Playback in Discord

  1. Open Discord and join a voice channel in a server where your bot has been invited
  2. In any text channel, type /play and enter a song name or YouTube URL when prompted
  3. The bot will join your voice channel, post an “Added to Queue” embed, and begin streaming the track
  4. A Now Playing embed will appear in the channel and the bot’s status will update to reflect the current track
Try /queue to see the paginated queue browser, /pause and /resume to control playback, and /skip to move to the next song.

Environment Variables

Verify the .env values the startup path depends on.

Lavalink Setup

Learn how to run the audio server that the quickstart depends on.

Bot Setup

Create the Discord application and invite link for the bot you are starting.

Playback Commands

Read the detailed command guide once the bot is up and running.