Skip to main content
This guide will help you set up and run MusicBot on your system. You’ll go from zero to playing music in your Discord server in just a few steps.

​
Prerequisites

Before you begin, make sure you have:
  • Python 3.8 or higher installed
  • FFmpeg installed on your system
  • A Discord account
  • Basic familiarity with command line interfaces

​
Setup steps

1

Clone the repository

Clone the MusicBot repository to your local machine:
git clone https://github.com/spyflow/musicbot.git
cd musicbot
2

Install dependencies

Install the required Python packages:
pip install discord.py yt-dlp pynacl python-dotenv
Install FFmpeg (required for audio processing):Ubuntu/Debian:
sudo apt install ffmpeg
macOS:
brew install ffmpeg
Windows:
Download from ffmpeg.org and add to your PATH.
3

Create a Discord bot

Follow these steps to create your Discord bot:
  1. Go to the Discord Developer Portal
  2. Click “New Application” and give it a name
  3. Navigate to the “Bot” section in the left sidebar
  4. Click “Add Bot” and confirm
  5. Under the bot’s username, click “Reset Token” and copy the token (you’ll need this next)
  6. Enable the following Privileged Gateway Intents:
    • Presence Intent
    • Message Content Intent
Keep your bot token secret! Never share it or commit it to version control.
4

Get a YouTube API key

The bot uses the YouTube Data API v3 for searching videos:
  1. Go to the Google Cloud Console
  2. Create a new project or select an existing one
  3. Enable the “YouTube Data API v3”
  4. Go to “Credentials” and create an API key
  5. Copy the API key (you’ll need it next)
YouTube Data API v3 has a free quota of 10,000 units per day, which is sufficient for most small to medium-sized Discord servers.
5

Configure environment variables

Create a .env file in the project root directory:
touch .env
Add your API credentials to the .env file:
YOUTUBE_API_KEY=your_youtube_api_key_here
DISCORD_BOT_TOKEN=your_discord_bot_token_here
Replace your_youtube_api_key_here and your_discord_bot_token_here with your actual credentials from the previous steps.
The bot will automatically create a music/ directory for caching downloaded songs when it first runs.
6

Invite the bot to your server

Generate an invite link for your bot:
  1. In the Discord Developer Portal, go to “OAuth2” → “URL Generator”
  2. Select the following scopes:
    • bot
    • applications.commands
  3. Select the following bot permissions:
    • Connect
    • Speak
    • Use Voice Activity
    • Send Messages
    • Read Message History
  4. Copy the generated URL and open it in your browser
  5. Select the server where you want to add the bot and authorize
7

Run the bot

Start the bot with Python:
python bot.py
You should see output similar to:
2026-03-04 10:30:15,123:INFO:discord: Bot connected as MusicBot (ID: 123456789)
2026-03-04 10:30:15,124:INFO:discord: Bot is ready and listening on 1 server(s).
Keep this terminal window open while you want the bot to run. For production deployments, consider using a process manager like PM2 or systemd.
8

Test your first command

Join a voice channel in your Discord server and try playing a song:
!play never gonna give you up
The bot will:
  1. Search YouTube for the query
  2. Download the audio (first time only)
  3. Join your voice channel
  4. Start playing the song
You can also use a direct YouTube URL:
!play https://www.youtube.com/watch?v=dQw4w9WgXcQ
The first time you play a song, it will take a few seconds to download. Subsequent plays of the same song will be instant thanks to caching.

​
What’s next?

Now that your bot is running, explore more features:

All commands

Learn about !skip, !leave, !ping, and more

Configuration

Customize bot prefix, inactivity timeout, and other settings

Troubleshooting

Common issues and how to resolve them

Architecture

Learn about the bot’s internal architecture

​
Quick command reference

Here are the essential commands to get you started:
CommandDescriptionExample
!play <query>Play a song by name or URL!play bohemian rhapsody
!skipSkip the current song!skip
!leaveDisconnect and clear queue!leave
!pingCheck voice connection latency!ping
!clearcacheClear cached songs for your server!clearcache
The bot automatically disconnects after 5 minutes of inactivity to save resources. This is configured in bot.py:25 with the inactive_time variable.

Build docs developers (and LLMs) love

Get started for freeTalk to us