yt-search-python v2.1.1 🚩

Search and read YouTube data (videos, playlists, channels, comments, transcripts) without the YouTube Data API v3 — no API key, no quota limits.

Installation • Quick Start • Key Classes • Examples • Known Limitations • Testing

---

What this library does

It talks to YouTube's own internal (innertube) endpoints — the same ones the youtube.com website itself calls — and parses the JSON back into clean Python structures. Both a synchronous API (youtubesearchpython) and an async API (youtubesearchpython.future) are provided, sharing the same underlying parsing logic so their results match.

Previous users of youtube-search-python: replace youtubesearchpython.__future__ imports with youtubesearchpython.future — nothing else changes.

---

Installation

pip3 install yt-search-python

Or from source:

pip install git+https://github.com/BillaSpace/yt-search-python.git

---

Quick Start

Search for videos

from youtubesearchpython import VideosSearch

search = VideosSearch('Hindutva', limit=10)
print(search.result())

Get video info + streaming formats

from youtubesearchpython import Video

video = Video.get('https://www.youtube.com/watch?v=aqz-KE-bpKQ')
print(video['title'], video['viewCount'])

Async

import asyncio
from youtubesearchpython.future import VideosSearch, Video

async def main():
    search = VideosSearch('Learn Python', limit=5)
    print(search.result())
    await search.next()          # next page
    print(search.result())

    video = await Video.get('aqz-KE-bpKQ')
    print(video['title'])

asyncio.run(main())

---

Key Classes

Search

• VideosSearch, ChannelsSearch, PlaylistsSearch, CustomSearch, ChannelSearch

Content

• Video — info + streaming formats (Video.get, Video.getInfo, Video.getFormats)
• Playlist — one-shot Playlist.get(...), or instantiate Playlist(link) for .getNextVideos() pagination
• Channel — Channel.get(...), or instantiate + .init() / .next() for pagination
• Comments — Comments.get(...), or instantiate + .init() / .getNextComments()
• Transcript — Transcript.get(link, params=<languageCode>) to select a specific caption track
• Hashtag — instantiate Hashtag(tag, limit=...) (fetches immediately) or Hashtag.get(...)
• Suggestions — autocomplete text suggestions. Suggestions.get(...) for one-shot use, Suggestions.session(...) (async: same) to reuse a client across many calls
• Recommendations — related/up-next videos for a video ID

Utility

• StreamURLFetcher — direct stream URLs (needs yt-dlp & denoinstalled in your system)
• ResultMode — .dict or .json output

Note: Suggestions (autocomplete text) and Recommendations (related videos) are deliberately separate classes — different endpoints, different data — not merged into one.

---

Examples

Advanced search with filters

from youtubesearchpython import CustomSearch, VideoSortOrder

search = CustomSearch('Python', VideoSortOrder.viewCount, limit=10)
print(search.result())

Playlist videos (works with a URL or a bare ID)

from youtubesearchpython import Playlist

playlist = Playlist.get('PLRBp0Fe2GpgmsW46rJyudVFlY6IYjFBIK')
print(playlist['info']['title'], len(playlist['videos']))

Comments

from youtubesearchpython import Comments

comments = Comments.get('https://www.youtube.com/watch?v=aqz-KE-bpKQ')
for c in comments['result'][:5]:
    print(c['author']['name'], ':', c['content'])

Search suggestions

from youtubesearchpython import Suggestions

print(Suggestions.get('Arijit Singh', language='en', region='US'))

Pagination

search = VideosSearch('Python', limit=10)
print(search.result())
search.next()
print(search.result())

Language & region

search = VideosSearch('Music', limit=10, language='es', region='ES')

Filters available

• Upload date: VideoUploadDateFilter.lastHour, .today, .thisWeek, .thisMonth, .thisYear
• Duration: VideoDurationFilter.short, .long
• Sort order: VideoSortOrder.relevance, .uploadDate, .viewCount, .rating

---

Known Limitations

Being upfront about what this library can't do, rather than silently under-delivering:

• Mix / Radio playlists (IDs starting with RD…) are auto-generated by YouTube through a different, session-based mechanism than regular playlists, and aren't returned by the standard browse endpoint this library uses. Playlist.get() will raise a clear YouTubeParseError identifying this case rather than crashing with an unrelated TypeError — but it won't fetch the mix's videos.
• Recommendations reflect what YouTube's own backend returns for an anonymous, session-less request to the /next endpoint — without real watch history or a signed-in session, YouTube itself mixes in generic suggestions alongside genuinely related videos. This is backend behavior, not something a scraper can fully correct.
• This library depends entirely on YouTube's internal response shapes, which change without notice. If something breaks, it's almost always a shape change on YouTube's end.

---

Covers all search classes, content retrieval, comments/recommendations/suggestions, StreamURLFetcher, transcripts — both sync and async.

---

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit and push
4. Open a Pull Request

---

License

MIT — see LICENSE.

Disclaimer

Not affiliated with YouTube or Google. Uses YouTube's publically available internal endpoints, which may change without notice. Use responsibly and in accordance with YouTube's Terms of Service.

Credits

» Current maintainer: Prakhar Shukla

» Original author: Hitesh Kumar Saini

Full acknowledgements

• Thanks to CertifiedCoder for his work on the request layer[ v2.0.0.]
• Built on top of the original youtube-search-python project and its contributors.

---