Registry / http-networking / ytmusicapi

ytmusicapi

JSON →
library1.12.1pypypi✓ verified 73d ago

ytmusicapi is a Python 3 library that provides an unofficial API for interacting with YouTube Music. It emulates web client requests using user cookie data for authentication, allowing for browsing, library management, playlist manipulation, and more. The current version is 1.11.5 and it maintains an active release cadence with frequent updates. [1, 7]

pip install ytmusicapi
INSTALL
IMPORT
SIG · YTMUSICAPI
Y
ytmusicapi
http-networkingpythonv1.12.1
Install
2.2s avg
Import
702ms
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.12.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.746s · 22.2MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 2.2s · import 0.657s · 23MB
20MB installed
● package 20MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

YTMusic
from ytmusicapi import YTMusic

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.")
Debug
Known issues
breakingOlder 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`.
affects: < 1.0.0 (for CLI), < 0.24.0 (for library)
gotchaOAuth 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]
affects: All versions, intermittent
deprecatedThe `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]
affects: < 1.0.0
Errors
Common errors & fixes
ytmusicapi: command not found
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.
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]
Upgrade
Version history
1.12.1latest on PyPI · released Jun 5, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
62 hits · last 30 days
node
54
Resources
ytmusicapi — pip install ytmusicapi · libregistry