gold-dl 2026.1.20.1

Library GoLD YouTube downloader (video / audio / shorts / playlists) with smart caching and auto quality handling

gold-dl — The simplest YouTube downloader (CLI + Python API)

Table of Contents

• Installation
• Upgrade
• Quick Start (CLI)
• Options
• Examples
• Python API
• Screenshots
• Todo
• Contributing
• License
• Badges / Usage

Channel Library : https://t.me/Source_Goldd Contact / Developer : @CB6BB

Installation

1. Verify you have Python 3.x:

python --version

2. Install gold-dl:

pip install gold-dl --break-system-packages

(If your environment does not require --break-system-packages, you may omit it.)

Upgrade

pip install --upgrade gold-dl --break-system-packages

Quick Start (CLI)

gold-dl "YOUTUBE_LINK" [PATH]

• "YOUTUBE_LINK" (required) the YouTube video or playlist URL (wrap in quotes).
• [PATH] (optional) destination folder; defaults to the current working directory.

Common options

• -v, --version
  • Show current version and exit.
• -a, --audio
  • Download audio only (skip video selection).
• -f, --footage
  • Download video only (skip audio-only flows).

Icons used in this README

• Download
• Audio
• Video
• Folder

Examples

# Download a video (interactive selection if needed)
gold-dl "https://www.youtube.com/watch?v=VIDEO_ID"

# Download audio only
gold-dl "https://www.youtube.com/watch?v=VIDEO_ID" --audio

# Download to a specific folder
gold-dl "https://www.youtube.com/watch?v=VIDEO_ID" ./downloads

# Download a playlist (you can select items or download all)
gold-dl "https://www.youtube.com/playlist?list=PLAYLIST_ID"

Python API (async) Use the async DownloadService to integrate gold-dl into bots and other apps.

import os
import asyncio
from typing import Union
from gold_dl import DownloadService

async def download(bot_username, link, video: Union[bool, str] = None):
    link = link
    loop = asyncio.get_running_loop()   
    def audio_dl():
        try:
            service = DownloadService(url=link, path="downloads/%(id)s.%(ext)s", quality="best", is_audio=True)
            result = service.download()
            return result
        except Exception:
            return None   
    def video_dl():
        try:          
            service = DownloadService(url=link, path="downloads/%(id)s.%(ext)s", quality="360p", is_audio=False)          
            result = service.download()
            return result
        except Exception:
            return None  
    if video:
        downloaded_file = await loop.run_in_executor(None, video_dl)
        return downloaded_file
    else:
        downloaded_file = await loop.run_in_executor(None, audio_dl)
        return downloaded_file

# Example runner:
# asyncio.run(download("botname", "https://www.youtube.com/watch?v=VIDEO_ID", video=None))

Direct Link (New) Use the async DownloadService to integrate gold-dl into bots and other apps.

import os
import asyncio
from typing import Union
from gold_dl import DownloadService

async def download(bot_username, link, video: Union[bool, str] = None):
    link = link
    loop = asyncio.get_running_loop()   
    def audio_dl():
        try:
            service = DownloadService(url=link, quality="best", is_audio=True)
            stream_url = service.get_direct_url(is_audio=True)
            if stream_url:
                return stream_url          
        except Exception:
            return None   
    def video_dl():
        try:
            service = DownloadService(url=link, quality="360p", is_audio=False)
            stream_url = service.get_direct_url(is_audio=False)
            if stream_url:
                return stream_url        
        except Exception:
            return None
    if video:  
        stream_url = await loop.run_in_executor(None, video_dl)
        return stream_url
    else:
        stream_url = await loop.run_in_executor(None, audio_dl)
        return stream_url

# Example runner:
# asyncio.run(download("botname", "https://www.youtube.com/watch?v=VIDEO_ID", video=None))

Screenshots

• Download video and choose save location
• Choose download type (audio / video)
• Select resolution when downloading video
• Playlist selection UI (pick single video(s) or download all)

Todo

• Notification System
• Auto Update package if new version available
• Support Optional Numbering for Downloaded Playlist Videos
• Improve code health
• API (Python)
• Download Playlist
• Support setting for default download folder
• Download thumbnails with videos and audio

Contributing

• Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
• Ensure code follows the existing style and add tests where applicable.
• Update the README and other documentation as necessary.

License

• See the LICENSE file in the project root (and the PyPI license badge above).