youtube-search-python

1.6.6 verified Fri May 01 auth: no python deprecated

A library to search for YouTube videos, channels, playlists, and retrieve video information without using the YouTube Data API v3. Uses InnerTube (YouTube's internal API) internally. Current version 1.6.6 is the final release; the project is deprecated. The author recommends migrating to yt-dlp for streaming and video info, and alternatives like youtube-search for searching.

pip install youtube-search-python

Common errors

error ModuleNotFoundError: No module named 'youtubesearch' ↓

cause Incorrect import path; the module is 'youtubesearchpython' not 'youtubesearch'.

fix

Use 'from youtubesearchpython import ...' instead of 'from youtubesearch import ...'.

error AttributeError: module 'youtubesearchpython' has no attribute 'VideosSearch' ↓

cause Older version of library (pre-1.0) or misspelled class name.

fix

Upgrade to latest version (pip install --upgrade youtube-search-python) and use correct class name: VideosSearch.

error KeyError: 'result' ↓

cause The search result dictionary structure changed between versions, or an error occurred during search.

fix

Check the returned object: print(result.keys()) and adapt your code. Also wrap in try-except to catch search failures.

Warnings

deprecated The library is deprecated as of v1.6.6 (final release). No further updates will be provided. It may break at any time due to YouTube changes. ↓

fix Migrate to alternative libraries: yt-dlp for streaming, youtube-search or google-api-python-client for searching.

breaking StreamURLFetcher and Video.get() for streaming URLs now require yt-dlp (since v1.6.1). They no longer use PyTube. ↓

fix Ensure yt-dlp is installed: pip install yt-dlp. Or use yt-dlp directly.

gotcha The package name is 'youtube-search-python' (PyPI), but the import module is 'youtubesearchpython'. Many users mistakenly import 'youtubesearch'. ↓

fix Use 'from youtubesearchpython import ...' (no dash, no underscore).

gotcha Search results may include age-restricted or unavailable videos. The library may raise exceptions for such content. ↓

fix Wrap searches in try-except to handle failures gracefully.

breaking Playlist class now uses InnerTube API (since v1.5.3). Series playlists are handled differently. ↓

fix Check updated documentation for Playlist class API changes.

Imports

VideosSearch

wrong

from youtubesearch import VideosSearch

correct

from youtubesearchpython import VideosSearch

Package is 'youtubesearchpython', not 'youtubesearch'

ChannelSearch

from youtubesearchpython import ChannelSearch

PlaylistsSearch

from youtubesearchpython import PlaylistsSearch

Video
```
from youtubesearchpython import Video
```
Used to get video info by URL
StreamURLFetcher
```
from youtubesearchpython import StreamURLFetcher
```
Deprecated in v1.6.6, use yt-dlp directly
Channel
```
from youtubesearchpython import Channel
```
Added in v1.6.3

Playlist

from youtubesearchpython import Playlist

Comments

from youtubesearchpython import Comments

Added in v1.6.0

Quickstart

Search for videos and print title and link.

from youtubesearchpython import VideosSearch

videos_search = VideosSearch('Never Gonna Give You Up', limit=2)
result = videos_search.result()
for video in result['result']:
    print(video['title'], video['link'])