ytscrape — Free YouTube Scraper for Python

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

from ytscrape import YouTube

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

ytscrape talks to YouTube's internal InnerTube API — the same endpoints the web app uses — and turns responses into typed, frozen dataclasses with transparent pagination. Pure HTTP: no Selenium, no Playwright, no API key. Sync (YouTube) and async (AsyncYouTube) share the same surface.

⚠️ This library uses YouTube's private endpoints. Use it responsibly and at your own risk — the endpoints may change over time.

Why ytscrape?

• 🔑 No API key, no quota — nothing to register, no billing project.
• 🧊 No browser — pure HTTP only.
• 🧩 Typed models (Video, Channel, Comment, Transcript, …) + py.typed.
• 💬 Every comment — replies included; CommentSort.NEWEST does not hide any.
• 📄 Transparent pagination — just iterate; continuation tokens are handled for you.
• 🌍 Localisation — language (hl) and region (gl), validated ISO codes.
• ⚡ Sync & async — optional httpx extra for AsyncYouTube.
• 🖥️ CLI included — ytscrape search "python" --max 10.
• 📤 JSON / CSV export — video.to_json(), dumps_csv(results), or ytscrape search "python" --format json.

Installation

pip install ytscrape            # or: uv add ytscrape
pip install "ytscrape[async]"   # optional async API (httpx)

Requires Python 3.10+. Runtime deps: requests, pycountry, defusedxml (+ httpx with the async extra).

Quick start

from ytscrape import YouTube, SearchFilter, CommentSort

with YouTube(language="en", region="US") as yt:
    for video in yt.search("python", filter=SearchFilter.VIDEOS, max_results=20):
        print(video.title, "-", video.url)

    details = yt.video("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
    print(details.title, details.channel, details.views, details.length_seconds)

    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}")

Async (same methods, await / async for):

import asyncio
from ytscrape import AsyncYouTube, SearchFilter


async def main() -> None:
    async with AsyncYouTube(max_concurrency=8) as yt:
        async for video in await yt.search(
            "python", filter=SearchFilter.VIDEOS, max_results=5
        ):
            print(video.title)


asyncio.run(main())

📂 Runnable sync + async snippets for every feature: examples/ · full guides: vsmutok.github.io/ytscrape

Feature coverage

ytscrape vs. the alternatives

How it works

High-level flow — sync and async share the same models and parsing layer:

graph LR
    User[User code / CLI] --> Facade[YouTube / AsyncYouTube]
    Facade --> Client[InnerTubeClient / AsyncInnerTubeClient]
    Facade --> Results[Lazy results / comment threads]
    Client --> InnerTube[YouTube InnerTube API]
    Client --> Context[InnerTube context]
    Results --> Client
    Client --> Parsing[parsing helpers]
    Results --> Parsing
    Parsing --> Models[Frozen dataclasses]
    Models --> User

1. Load youtube.com once and extract the InnerTube context (API key, client version, visitor data).
2. POST to youtubei/v1/search, player, browse, next, etc. with that context.
3. Parse responses into frozen dataclasses; continuation tokens are followed while you iterate.

Documentation

Deep dives live on the docs site (not duplicated here):

CLI cheatsheet

The CLI prints colourful boxed tables under a mini ▶ ytscrape wordmark, with a spinner while requests are in flight:

ytscrape search "python tutorial" --filter videos --max 10
ytscrape --language uk --region UA search "музика" --max 10
ytscrape video https://www.youtube.com/watch?v=dQw4w9WgXcQ
ytscrape channel @RickAstleyYT
ytscrape transcript dQw4w9WgXcQ --lang en
ytscrape comments https://youtu.be/dQw4w9WgXcQ --replies --sort newest --max 20

python -m ytscrape … works too. Pass --max 0 to comments for no limit.

FAQ

Contributing

Bug reports, ideas and PRs are welcome — see CONTRIBUTING.md.

git clone https://github.com/vsmutok/ytscrape && cd ytscrape
uv sync --dev
uv run pytest
uv run pre-commit run --all-files

• 🗺️ todo: todo.md
• 📝 Changelog: CHANGELOG.md

License

MIT