youtube-comment-downloader: comments without the Data API

What the script actually does

youtube-comment-downloader is described as a simple script for downloading YouTube comments without using the YouTube API. The output is line delimited JSON by default, and the package can be used either as a command line tool or as a library.

The point of avoiding the API is practical rather than ideological. The Data API requires a project, a key, a quota and a request format, and for a one-off analysis of a handful of videos that setup costs more than the extraction. This script instead reads the same data the browser page loads, which means no credentials and no quota, at the cost of depending on the shape of that page.

That dependency is the whole risk of the approach, and it is worth being clear about it. A scraper of a web page works until the page changes, and YouTube changes it. The project's answer to that is frequency: the release history shows version 0.1.82 on 2026-07-29, 0.1.83 on 2026-07-30 and 0.1.84 on 2026-10-15, and the last push to the repository was on 2026-10-15. The version numbers and the cadence suggest a tool that is kept working as the target changes, which is what you want from a scraper, and the cost is that every user is running an unofficial client.

The project is MIT licensed and written in Python, with only two runtime dependencies, requests and dateparser, listed in requirements.txt.

Installing it

The README recommends installing inside a Python virtual environment, and the package is on PyPI:

pip install youtube-comment-downloader

Installing straight from the repository is the alternative, which is what you want when you want the current state of master rather than the last release:

pip install https://github.com/egbertbouman/youtube-comment-downloader/archive/master.zip

The packaging is deliberately plain. setup.py contains a single setup() call with no arguments, which means the metadata lives in setup.cfg, and pyproject.toml only declares the setuptools build backend and its requirements. The project uses a src-less layout with the package directory at the top level next to tests/ and requirements-testing.txt, and a GitHub Actions workflow is referenced for the test run.

Two dependencies carry the actual work. requests does the HTTP, and dateparser is there for the timestamps, since YouTube returns comment times in a format that has to be normalised before it is useful in a dataset. That dateparser dependency is a small signal about the data model: the script does not just fetch comment text, it tries to give you dates you can sort by.

The command line interface

The tool takes either a video id or a full URL, and the rest of the options control the output. The most common invocation is the URL form:

youtube-comment-downloader --url https://www.youtube.com/watch?v=ScMzIvxBSi4

and the id form with an explicit output file and format:

youtube-comment-downloader --youtubeid ScMzIvxBSi4 --output comments.csv --format csv

Without an output option, the file is named after the video id with the extension matching the format, so the first example writes ScMzIvxBSi4.jsonl.

The options that shape the extraction are these:

  --limit LIMIT, -l LIMIT                    Limit the number of comments
  --language LANGUAGE, -a LANGUAGE           Language for Youtube generated text (e.g. en)
  --sort SORT, -s SORT                       Whether to download popular (0) or recent comments (1). Defaults to 1

The sort option is worth reading carefully. It takes 0 for popular or 1 for recent, and it defaults to 1, so the default order is chronological rather than by likes. The language option applies to YouTube generated text rather than to the comments themselves, which covers the auto-translated titles and the translated descriptions that appear for a video in a different language.

One sharp edge is documented: a YouTube id that starts with a dash is parsed as an option by the argument parser, so it has to be passed with the equals form, -y=idwithdash or --youtubeid=idwithdash, rather than as a separate word. That is a standard argparse behaviour and an easy trap for a script that processes ids in a loop.

Output formats and the library API

Four output formats are supported and selected with the format option: jsonl, json, csv with comma separators and scsv with semicolon separators. The default is line delimited JSON, one comment per line, which is the right default for a data pipeline because a consumer can read the file line by line without parsing the whole thing into memory.

The CSV variants matter for a different audience. A comma separated file drops straight into a spreadsheet, and the semicolon separated variant exists because the comma is the decimal separator in several European locales, which would otherwise break a numeric column.

Used as a library, the same functionality is available through a class:

from itertools import islice
from youtube_comment_downloader import *
downloader = YoutubeCommentDownloader()
comments = downloader.get_comments_from_url('https://www.youtube.com/watch?v=ScMzIvxBSi4', sort_by=SORT_BY_POPULAR)
for comment in islice(comments, 10):
    print(comment)

The important detail is that get_comments_from_url returns a generator rather than a list, which is why the example wraps it in islice to take the first ten. A generator is the right design for a comment collection, since a popular video can have hundreds of thousands of comments and a list of them would not fit in memory. The cost is that the extraction happens lazily, so a failure partway through a large download leaves you with a partial file and no easy way to resume.

The sort is passed as a constant, SORT_BY_POPULAR in the example, with the equivalent constant for the recent order being the default on the command line.

Where youtube-comment-downloader is the wrong tool

The first case is a job that has to run repeatedly and at scale. The Data API gives a quota, a stable contract and a documented pagination model, and a team that needs comments from thousands of videos over months needs that contract. This script optimises for the single video, and there is no resume, no rate limit handling and no retry policy described in the README.

The second case is a project with terms that require the official interface. A company analysing comments about its own product may be required to use the API, and a script that scrapes the page is not compliant with an API terms of service agreement. This is a legal and policy question rather than a technical one, and the difference between the two approaches is not a matter of taste.

The third limitation is stability of the data model. Because the tool reads the page, the fields it returns are whatever the page exposes, and they change when YouTube changes them. A script that parses the responses into a fixed structure is doing the work of versioning, and it is doing it without a changelog. The project's own release cadence is the mitigation, and it is a decent one, but a team that stores a corpus over years has to accept that a field may disappear or change meaning between two runs.

The official API remains the right tool for anything that has to be reproducible. What this script offers that the API does not is zero setup, and for a one-off analysis of a video you may not be able to watch, that is often enough.

Editorial conclusion

youtube-comment-downloader fits a researcher or analyst who needs a comment corpus for a specific video and does not want an API key or a quota, and the JSONL output pipes straight into a data pipeline. It does not fit a job that needs to run continuously at scale or that must respect YouTube's API terms, since this tool scrapes the page instead. Check first that the sort order you need is available, because only popular and recent are supported.

Frequently asked questions

Official sources

1. egbertbouman/youtube-comment-downloader on GitHub
2. Issues
3. License: MIT
4. README
5. Releases