YouTube Music API (Unofficial)

Common errors

• ytmusicapi: command not found

  cause The `ytmusicapi` command-line interface (CLI) was introduced in version 1.0.0. If you are on an older Python version (e.g., Python 3.6) that pulls an older `ytmusicapi` version, the CLI will not be available. Also, ensure `~/.local/bin` is in your PATH. [18]
  fix Upgrade Python to 3.10 or higher and reinstall `ytmusicapi` (`pip install --upgrade ytmusicapi`). Verify `~/.local/bin` is in your system's PATH environment variable for the executable to be found.

• ytmusicapi.exceptions.YTMusicServerError: Server returned HTTP 400: Bad Request. Request contains an invalid argument.

  cause This error typically indicates an issue with the authentication credentials, particularly when using OAuth. The provided `oauth.json` might be invalid, expired, or YouTube Music's API might be rejecting the request for an unknown reason. [15, 17]
  fix Try generating a new `oauth.json` file by re-running the OAuth authentication flow. If the problem persists, consider switching to browser authentication (`browser.json`) as a more stable alternative for some use cases. [15]

Warnings

• breaking Older Python versions (e.g., Python 3.6) are not supported by recent `ytmusicapi` versions (>= 0.24.0). The `ytmusicapi` CLI tool, including for OAuth setup, was introduced in version 1.0.0, requiring Python 3.10 or higher. [18]
  Fix: Upgrade to Python 3.10 or newer. Use `pip install --upgrade python` (or your system's Python management tool) and then `pip install ytmusicapi`.
• gotcha OAuth authentication can intermittently fail with a 'HTTP 400: Bad Request' error. This often occurs seemingly at random or after a period of working correctly. [15, 17]
  Fix: If encountering frequent '400 Bad Request' errors with OAuth, switch to browser-based authentication (using `browser.json`). Ensure your `oauth.json` is correctly generated, or regenerate it if the issue persists. Often, browser auth proves more robust for personal use. [15]
• deprecated The `YTMusic.setup()` method was used in older versions for setting up browser authentication. While it might still be present, the documentation now emphasizes direct initialization with the auth file or using `ytmusicapi.auth.browser.setup_browser` for programmatic header parsing. [6, 14, 19]
  Fix: For new projects or updating existing ones, directly pass the path to `browser.json` or `oauth.json` to the `YTMusic()` constructor. Refer to the current documentation for the latest recommended setup procedures, especially `from ytmusicapi.auth.browser import setup_browser` for generating the browser.json programmatically from cURL headers. [14]

Install

• pip install ytmusicapi Install stable version

Imports

• YTMusic

  from ytmusicapi import YTMusic

Quickstart

This quickstart demonstrates how to initialize `ytmusicapi` for both authenticated and unauthenticated requests. It shows a basic search for a song and retrieving the first few library playlists. Authentication typically requires either an `oauth.json` or `browser.json` file, which should be generated by following the detailed steps in the official ytmusicapi documentation. For a secure production environment, the path to this authentication file should be managed via environment variables. [1, 2, 3, 4]

import os
from ytmusicapi import YTMusic

# --- Authentication (choose one) ---
# Option 1: Using browser headers (recommended for personal use)
# Create 'browser.json' by following instructions in the ytmusicapi documentation (developer tools network tab -> copy as cURL).
# For programmatic setup, use `from ytmusicapi.auth.browser import setup_browser`
# Example: yt = YTMusic('browser.json')

# Option 2: Using OAuth (requires Google Cloud Project setup, often more stable for automated scripts)
# Create 'oauth.json' by following instructions in the ytmusicapi documentation (Google Cloud Console -> OAuth client ID).
# Example: yt = YTMusic('oauth.json')

# For unauthenticated requests (limited functionality):
yt = YTMusic()

# Use an environment variable for the auth file path in production
auth_file = os.environ.get('YTMUSIC_AUTH_FILE', 'oauth.json') # or 'browser.json'

try:
    yt = YTMusic(auth_file)
    # Perform a search
    search_results = yt.search('Eminem Lose Yourself', filter='songs')
    if search_results:
        print(f"Found song: {search_results[0]['title']} by {search_results[0]['artist']['name']}")
    else:
        print("No results found.")

    # Get library playlists
    playlists = yt.get_library_playlists(limit=5)
    if playlists:
        print("\nYour first 5 library playlists:")
        for playlist in playlists:
            print(f"- {playlist['title']} (ID: {playlist['playlistId']})")
    else:
        print("No library playlists found.")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure your authentication file (oauth.json or browser.json) is correctly set up and accessible.")