ytscrape — Free YouTube Scraper for Python

Scrape YouTube search results, video metadata and comments — no API key, no quota, no browser.

ytscrape is a free YouTube scraper for Python built on top of the internal YouTube InnerTube API — the same endpoints the YouTube web app uses. Use it to search YouTube, extract video, channel and playlist data, fetch video metadata and collect every comment (and reply) of a video — all with transparent pagination, typed models and no API key.

from ytscrape import YouTube

with YouTube() as yt:
    for video in yt.search("python", max_results=5):
        print(video.title, video.url)

⚠️ This library talks to YouTube's private endpoints. Use it responsibly and at your own risk; the endpoints and params values may change over time.

Table of Contents

• Why ytscrape?
• Installation
• Quick start
• Feature coverage
• ytscrape vs. the alternatives
• How it works
• Search
• Video details
• Channel details
• Comments
• Language & country
• Pagination
• Data models
• Error handling
• Advanced: proxies, retries, custom sessions
• Command line
• Examples
• FAQ
• Roadmap
• Contributing
• License

Why ytscrape?

• 🔑 No YouTube Data API key, no quota, no sign-up, no billing project.
• 🧊 No browser — no Selenium, no Playwright, no headless Chrome. Pure HTTP.
• 🧩 Typed models (Video, Channel, Playlist, VideoDetails, ChannelDetails, Comment) instead of raw, deeply-nested JSON.
• 📄 Transparent pagination — just iterate; continuation tokens are handled for you.
• 💬 Full comment scraping, including replies and the sort order that actually returns every comment.
• 🌍 Localisation — interface language (hl) and content region (gl), validated with pycountry.
• 🪶 Tiny install — only requests and pycountry.
• 🖥️ CLI included: ytscrape search "python" --max 10.
• 🧱 Clean, extensible OOP design (facade + factory methods + strategy) — easy to build on or to mock in tests.

Installation

pip install ytscrape

or with uv:

uv add ytscrape

From source:

pip install .

Requires Python 3.10+. Runtime dependencies: requests, pycountry.

Quick start

Everything you usually need, in one snippet:

from ytscrape import YouTube, SearchFilter, CommentSort

with YouTube(language="en", region="US") as yt:
    # 1. Search videos and iterate over as many pages as needed.
    for video in yt.search("python", filter=SearchFilter.VIDEOS, max_results=20):
        print(video.title, "-", video.url)

    # 2. Search channels.
    for channel in yt.search("python", filter=SearchFilter.CHANNELS, max_results=5):
        print(channel.title, channel.url)

    # 3. Fetch details for a single video (id or URL both work).
    details = yt.video("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
    print(details.title, details.channel, details.views, details.length_seconds)

    # 4. Collect comments — including replies and *every* comment.
    for comment in yt.comments(
        "https://youtu.be/dQw4w9WgXcQ",
        include_replies=True,
        sort=CommentSort.NEWEST,
        max_results=100,
    ):
        marker = "  ↳" if comment.is_reply else "-"
        print(f"{marker} {comment.author}: {comment.text}")

📂 More runnable snippets live in examples/.

Feature coverage

ytscrape vs. the alternatives

Rule of thumb: use yt-dlp when you need to download media, the official Data API when you need guaranteed, ToS-blessed access, and ytscrape when you need fast, key-less access to YouTube metadata and comments from Python.

How it works

ytscrape speaks the private YouTube InnerTube API directly:

1. It loads youtube.com once and extracts the InnerTube context (API key, client version, visitor data).
2. It POSTs to youtubei/v1/search, youtubei/v1/player, youtubei/v1/browse and youtubei/v1/next with that context.
3. Responses are parsed into small, frozen dataclasses; continuation tokens are followed automatically while you iterate.

No browser. No Selenium. No Playwright. Pure HTTP.

Search

from ytscrape import YouTube, SearchFilter

with YouTube() as yt:
    for item in yt.search("lofi", filter=SearchFilter.PLAYLISTS, max_results=10):
        print(item.title, item.url)

You can also pass the string form: yt.search("python", filter="videos") — no magic EgIQAQ== strings in your code.

Video details

with YouTube() as yt:
    video = yt.video("dQw4w9WgXcQ")  # id
    video = yt.video("https://youtu.be/dQw4w9WgXcQ")  # or any URL

    print(video.title, video.views, video.length_seconds, video.is_live)
    print(video.keywords)

watch?v=, youtu.be/, /shorts/ and /embed/ URLs are all accepted.

Channel details

with YouTube() as yt:
    channel = yt.channel("UCuAXFkgsw1L7xaCfnd5JJOw")  # id
    channel = yt.channel("@RickAstleyYT")  # handle
    channel = yt.channel("https://www.youtube.com/@RickAstleyYT")  # or any URL

    print(channel.title, channel.subscribers, channel.video_count)
    print(channel.country, channel.joined_date, channel.view_count)
    print(channel.photo, channel.banner)
    print(channel.links)  # e.g. {"x": "https://twitter.com/…", "instagram": "…"}
    print(channel.handle, channel.keywords[:5])
    print(channel.url, channel.vanity_url, channel.rss_url)

# Transcripts / captions (manual preferred over auto-generated).
transcript = yt.transcript("dQw4w9WgXcQ", languages=["uk", "en"])
print(transcript.language_code, transcript.is_generated, len(transcript))
for line in transcript[:3]:
    print(f"{line.start:.1f}s  {line.text}")

# Or inspect tracks first:
for track in yt.transcripts("dQw4w9WgXcQ"):
    print(track.language_code, track.is_generated, track.is_translatable)

/channel/UC…, /@handle, /c/… and /user/… URLs are all accepted. Handles are resolved to a UC… id automatically.

Comments

YouTube.comments() returns a lazy CommentThread that transparently pages through every comment:

from ytscrape import YouTube

with YouTube() as yt:
    for comment in yt.comments("https://youtu.be/dQw4w9WgXcQ", max_results=50):
        print(comment.author, "-", comment.text)

Replies. By default only top-level comments are collected. Pass include_replies=True to also collect the replies of every thread; each reply has is_reply=True and is yielded right after the comment it replies to:

for comment in yt.comments(video_url, include_replies=True):
    marker = "  ↳" if comment.is_reply else "-"
    print(f"{marker} {comment.author}: {comment.text}")

Omit max_results to iterate over all comments. When include_replies=True, max_results counts replies too. A ParseError is raised if the video has comments disabled.

Collecting every comment (sort order)

YouTube's default "Top comments" view quietly hides some comments (less relevant ones and "potential spam"), so collecting in that order will appear to skip comments. To get every comment, switch to "Newest first":

from ytscrape import YouTube, CommentSort

with YouTube() as yt:
    # `CommentSort.NEWEST` (or the string "newest") returns every comment.
    for comment in yt.comments(video_url, sort=CommentSort.NEWEST):
        print(comment.author, "-", comment.text)

sort accepts a CommentSort (TOP / NEWEST) or its string value; it defaults to CommentSort.TOP to mirror YouTube's own default view.

Counting what you collected

comments() is a lazy iterator, so the total is known only after the last page:

total = 0
for comment in yt.comments(video_url, sort="newest"):
    total += 1
print(f"Collected {total} comments")

# Or materialise everything at once:
comments = list(yt.comments(video_url, sort="newest"))
print(len(comments))

Language & country

YouTube localises results by interface language (hl) and content region (gl). Configure both when creating YouTube, passing plain ISO codes (or the Language / Country value objects, which wrap the same codes):

from ytscrape import YouTube, Language, Country, Locale

# Just pass raw ISO codes — they are validated and normalised for you.
with YouTube(language="uk", region="UA") as yt:
    for video in yt.search("музика", max_results=10):
        print(video.title, video.url)

# The Language / Country value objects are equivalent (and reusable).
yt = YouTube(language=Language("de"), region=Country("DE"))

# Invalid codes are rejected early (validated with pycountry).
YouTube(region="XX")  # ValueError: Unknown country code 'XX'. ...

# Or pass a ready-made Locale.
yt = YouTube(locale=Locale(language="fr", country="FR"))
print(yt.locale.language.code, yt.locale.country.code)  # fr FR

Language and Country are thin, self-validating value objects around a raw ISO 639-1 / ISO 3166-1 alpha-2 code — there is no hard-coded list, so any valid code works. The chosen locale is sent both in the request context (hl / gl) and as the Accept-Language HTTP header.

Pagination

Pagination is transparent — iterating over the result object automatically loads the next page:

results = yt.search("python")

for item in results:  # loads pages on demand
    print(item.title)

You can also page manually:

results = yt.search("python")
print(len(results.fetch_next_page()))  # explicitly load one more page
print(results.has_more)  # is there another page?

Use max_results to cap how many items you consume.

Data models

All models are frozen dataclasses with full type hints (the package ships py.typed, so mypy/pyright see the types).

Video (search results) — video_id, title, channel, channel_id, duration, views, published, thumbnail, url.

Channel — channel_id, title, handle, subscribers, video_count, thumbnail, url.

Playlist — playlist_id, title, channel, video_count, thumbnail, url.

VideoDetails (from YouTube.video()) — video_id, title, description, channel, channel_id, length_seconds (int), views (int), keywords, is_live, thumbnail, url.

ChannelDetails (from YouTube.channel()) — channel_id, title, description, handle, subscribers, video_count, view_count, keywords, tags, thumbnail / photo (avatar), banner, vanity_url, rss_url, is_family_safe, available_countries, country, joined_date, links (dict like {"x": "…", "instagram": "…"}), url.

Comment:

Error handling

Every error raised by the library derives from YtScraperError:

from ytscrape import YouTube, YtScraperError, RequestError, ParseError

try:
    with YouTube() as yt:
        for comment in yt.comments("dQw4w9WgXcQ"):
            print(comment.text)
except RequestError as exc:  # network / HTTP problem
    print("network error:", exc)
except ParseError as exc:  # unexpected response (e.g. comments disabled)
    print("cannot parse:", exc)
except YtScraperError as exc:  # catch-all
    print("ytscrape failed:", exc)

Advanced: proxies, retries, custom sessions

YouTube is a thin facade over InnerTubeClient, which accepts your own requests.Session — that is the hook for proxies, retries, custom headers or caching:

import requests
from requests.adapters import HTTPAdapter, Retry
from ytscrape import YouTube, InnerTubeClient

session = requests.Session()
session.proxies = {"https": "http://user:pass@proxy:8080"}
session.mount("https://", HTTPAdapter(max_retries=Retry(total=5, backoff_factor=1)))

client = InnerTubeClient(session=session, timeout=15.0, language="en", region="US")

with YouTube(client=client) as yt:
    print(next(iter(yt.search("python"))).title)

The same injection point makes the library trivial to unit-test: pass a fake session and no network call ever happens.

Command line

# Search
python -m ytscrape search "python tutorial" --filter videos --max 10

# Localised search (Ukrainian interface, Ukrainian region)
python -m ytscrape --language uk --region UA search "музика" --max 10

# Video details
python -m ytscrape video https://www.youtube.com/watch?v=dQw4w9WgXcQ

# Channel details
python -m ytscrape channel @RickAstleyYT
python -m ytscrape transcript dQw4w9WgXcQ --lang en
python -m ytscrape transcript dQw4w9WgXcQ --list

# Collect comments (pass 0 to --max for no limit)
python -m ytscrape comments https://www.youtube.com/watch?v=dQw4w9WgXcQ --max 20

# Collect comments together with their replies
python -m ytscrape comments https://www.youtube.com/watch?v=dQw4w9WgXcQ --replies

# Collect EVERY comment (the default "top" order hides some)
python -m ytscrape comments https://www.youtube.com/watch?v=dQw4w9WgXcQ --sort newest

After installing, a ytscrape console script is also available:

ytscrape search "python" --filter channels --max 5

Examples

FAQ

Roadmap

• ⚡ Async API (asyncio / httpx) alongside the synchronous one.
• 📺 Channel tabs: videos, Shorts, live, playlists, about.
• 🎵 Playlist items with transparent pagination.
• 🔗 Related videos, trending and home feed.
• 🗒️ Community posts.
• 📚 A dedicated documentation site with an API reference.

Ideas and votes are welcome in issues.

Contributing

Contributions are very welcome — bug reports, ideas and pull requests alike.

git clone https://github.com/vsmutok/ytscrape
cd ytscrape
uv sync --dev
uv run pytest              # run the test suite
uv run pre-commit run --all-files   # ruff + format + bandit

The project uses Ruff for linting and formatting, bandit for security checks and pre-commit to run them all. See CHANGELOG.md for release notes.

License

MIT