Need help with ytmdl?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

1.5K Stars 83 Forks MIT License 471 Commits 10 Opened issues


A simple app to get songs from YouTube in mp3 format with artist name, album name etc from sources like iTunes, LastFM, Deezer, Gaana etc.

Services available


Need anything else?

Contributors list

YouTube Music Downloader

Download songs from YouTube by getting the audio from YouTube and the metadata from sources like Itunes and Gaana.

Web App

Ytmdl also has an web app, you can try it out here

Why this?

This app downloads a song by getting the audio from Youtube sources using youtube-dl and then adds song information like artist name, album name, release date, thumbnail etc by fetching it from sources like Itunes, Gaana and other sources.

NO. YoutubeDL doesn't do that. All youtube-dl does is lets you download audio from a video that you specify. This app is not yet another youtube-dl clone.

Support the Project?

Help the development of this project by becoming a backer or a sponsor.

Become a Backer

Become a sponsor

If you like my work, consider buying me a coffee or donating. In case you want to become a patron, join my Pateron

undefined undefined undefined


  • Python 3.6.1
  • ffmpeg



pip install ytmdl

NOTE: System wide installation requires


Arch Linux

is available in AUR as
. It can be found here

NOTE: The git version is availble as

in AUR.


can be installed in Gentoo by the following commands
# First set up src_prepare-overlay (as root)
emerge -av --noreplace app-eselect/eselect-repository
eselect repository enable src_prepare-overlay
emaint sync -r src_prepare-overlay
# Finally emerge ytmdl (as root)
emerge -av --autounmask net-misc/ytmdl

Available in src_prepare-overlay here


You need to install

in order for
to work properly. This can be done by downloading the
binary from here. Once downloaded, extract the file and find the
file. Copy the directory's path and add it to PATH in the following way.
setx path "%path%;C:\your\path\here\"


is installed, install
using the following command
pip install ytmdl --upgrade

NOTE: You'll need to have Python 3.6.1 or more installed.

Optionally, also install the latest version of

using the following command:
pip install simber downloader-cli --upgrade


You can manually install

by cloning this repository and running the
  1. Install

    if it isn't already:
     pip install setuptools
  2. Clone this repo:

    git clone   
  3. Move into the

    directory and run the
    cd ytmdl
    sudo python install


usage: ytmdl [-h] [-q] [--song SONG-METADATA] [--choice CHOICE]
             [--artist ARTIST] [--album ALBUM] [--disable-metaadd]
             [--skip-meta] [-m] [--disable-sort] [--ask-meta-name]
             [--on-meta-error ON_META_ERROR] [--proxy URL] [--url URL]
             [--list PATH TO LIST] [--nolocal] [--format FORMAT] [--trim]
             [--version] [--keep-chapter-name] [--pl-start NUMBER]
             [--pl-end NUMBER] [--pl-items ITEM_SPEC] [--ignore-errors]
             [--title-as-name] [--level LEVEL] [--disable-file] [--list-level]
             [SONG_NAME ...]

positional arguments: SONG_NAME Name of the song to download. Can be an URL to a playlist as well. It will be automatically recognized.

optional arguments: -h, --help show this help message and exit -q, --quiet Don't ask the user to select songs if more than one search result. The first result in each case will be considered. --proxy URL Use the specified HTTP/HTTPS/SOCKS proxy. To enable SOCKS proxy, specify a proper scheme. For example socks5:// Pass in an empty string (--proxy "") for direct connection --url URL Youtube song link. --list PATH TO LIST Download list of songs. The list should have one song name in every line. --nolocal Don't search locally for the song before downloading. --format FORMAT The format in which the song should be downloaded. Default is mp3, but can be set in config. Available options are ['mp3', 'm4a', 'opus'] --trim, -t Trim out the audio from the song. Use underlying speech and music segmentation engine to determine and keep only the music in the file. Useful in songs where there are speeches, noise etc before/after the start of the song. Default is false. --version show the program version number and exit --keep-chapter-name Keep the title extracted from the chapter in order to search for the metadata. If not passed, the user will be asked if they'd like to change the title with which the metadata will be searched.

Metadata: --song SONG-METADATA The song to search in Metadata. Particularly useful for songs that have the names in a different language in YouTube. For Example, greek songs. --choice CHOICE The choice that the user wants to go for. Usefull to pass along with --quiet. Choices start at 1 --artist ARTIST The name of the song's artist. Pass it with a song name. --album ALBUM The name of the song's album. Pass it with a song name. --disable-metaadd Disable addition of passed artist and album keyword to the youtube search in order to get a more accurate result. (Default: false) --skip-meta Skip setting the metadata and just copy the converted song to the destination directory. '--manual-meta' will override this option, pass only one of them. -m, --manual-meta Manually enter song details. --disable-sort Disable sorting of the metadata before asking for input. Useful if the song is in some other language and/or just a few providers are used. --ask-meta-name Ask the user to enter a seperate name for searching the metadata (Default: false) --on-meta-error ON_META_ERROR What to do if adding the metadata fails for some reasong like lack of metadata or perhaps a network issue. Options are ['exit', 'skip', 'manual']

Playlist: --pl-start NUMBER Playlist video to start at (default is 1) --pl-end NUMBER Playlist video to end at (default is last) --pl-items ITEM_SPEC Playlist video items to download. Specify indices of the videos present in the playlist seperated by commas like: '--playlist-items 1, 2, 4, 6' if you want to download videos indexed 1, 2, 4 and 6. Range can also be passed like: '--playlist-items 1-3, 5-7' to download the videos indexed at 1, 2, 3, 5, 6, 7. --ignore-errors Ignore if downloading any video fails in a playlist. If passed, the execution will move to the next video in the passed playlist. --title-as-name Use the title of the video as the name of the song to search for metadata. If not passed, user will be asked if they want to use a different name and continue accordingly.

Logger: --level LEVEL The level of the logger that will be used while verbosing. Use --list-level to check available options. --disable-file Disable logging to files --list-level List all the available logger levels.



The defaults can be changed by editing the config file in ytmdl folder in your .config folder

The config will be created automatically the first time you run

and will be present in ~/.config/ytmdl/config

However, it can be created manually by the following command

mkdir -p ~/.config/ytmdl; curl > ~/.config/ytmdl/config

Above command will download the config from the repo and save it in the


Supported Options

As of the latest development branch, the following options can be changed from the config

| Name | Description | Default | |:--------------------:|----------------------------------------------------|--------------------------------| |

| Directory to save the songs in after editing | Current direcotry | |
| Quality of the song | 320kbps | |
| Which API providers to use for metadata | all supported options are used | |
| Default format of the song | mp3 | |
| What to do if error occurs while writing meta | exit |

Advanced Configuration

Dynamically storing songs

field also takes values that are extracted from the song being downloaded


field needs to be passed some special values in order to achieve that. The string is scanned and when a
sign occurs, the special string will start and each directory can be seperated by using an

To save the song in the

format, the following needs to be added in the

Above will extract to the following directory structure when a song named

by artist
Post Malone
from the album
Hollywood's Bleeding
   |--Hollywood's Bleeding
      |--Post Malone

In order to pass the name with which the song should be saved, the last attribute can be passed between


If the

field is
will extract to the following directory structure
   |--Hollywood's Bleeding
      |--Post Malone.mp3

Supported options for dynamic storing

As of the latest source, the following options can be passed to the special string in order to create dynamic directories

| Name | | |:-------------:|-------------------------------| |

| Artist Of the Song | |
| Album Of the Song | |
| Title Of the Song | |
| Genre Of the Song | |
| TrackNumber Of the Song | |
| ReleaseDate Of the Song |

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.