youtube-search

library2.2.0pypypi✓ verified 83d ago

A Python library to perform YouTube video searches without the official API. Version 2.2.0 is the latest stable release. It uses web scraping to retrieve search results, so it may break with YouTube changes.

pip install youtube-search

github ↗homepage ↗

INSTALL

IMPORT

SIG · YOUTUBE-SEARCH

youtube-search

searchpythonv2.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

YoutubeSearch

✓ from youtube_search import YoutubeSearch

✗ import youtube_search

The class is not the module itself; you need to import YoutubeSearch explicitly.

Simple search for 'test' returning up to 10 results as a list of dictionaries.

from youtube_search import YoutubeSearch results = YoutubeSearch('test', max_results=10).to_dict() print(results)

Debug

Known issues

breakingIn version 2.x, the API changed: use YoutubeSearch(query, max_results=N).to_dict() instead of the old search function.

fix

Update code to use the class-based API: results = YoutubeSearch('query', max_results=10).to_dict()

affects: >=2.0.0

gotchayoutube-search scrapes YouTube and may break if YouTube changes its layout. Results may be unreliable or empty.

fix

Consider using the official YouTube Data API for production use.

affects: all

gotchaTo get a list of dictionaries, call .to_dict() on the YoutubeSearch object. The object itself is iterable but yields strings, not dicts.

fix

Use .to_dict() to get structured results, or iterate over the object for raw strings.

affects: >=2.0.0

Errors

Common errors & fixes

ImportError: cannot import name 'YoutubeSearch' from 'youtube_search'

Using a very old version of the library (pre-2.0) or incorrect import path.

fix

Upgrade with pip install --upgrade youtube-search and ensure the import is: from youtube_search import YoutubeSearch

AttributeError: 'str' object has no attribute 'items'

Iterating over the YoutubeSearch object expecting dicts but getting strings.

fix

Use .to_dict() to get a list of dictionaries, not direct iteration.

youtube_search.YoutubeSearch is not callable

Trying to call YoutubeSearch as a function instead of instantiating it as an object.

fix

Instantiate: results = YoutubeSearch('query', max_results=10).to_dict()

Upgrade

Version history

2.2.0latest on PyPI · released Dec 6, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

54 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/joetats/youtube_search ↗

homepagehttps://github.com/joetats/youtube_search ↗