youtube-transcript-api

To set up the repository for local development, you must have poetry installed. Run the following command to install the necessary dependencies, including test and development groups:

poetry install --with test,dev

The project uses poe tasks to manage testing, coverage, linting, and formatting. You can run these individual tasks or use the precommit task to run all checks required for a successful build.

# Individual tasks
poe test
poe coverage
poe format
poe lint

# Run all necessary checks for a green build
poe precommit

Install the module using pip to integrate it into your Python application.

pip install youtube-transcript-api

If you encounter RequestBlocked or IpBlocked exceptions (common when using cloud providers like AWS or GCP), you can use rotating residential proxies. The library provides built-in support for Webshare.

To use Webshare, initialize YouTubeTranscriptApi with a WebshareProxyConfig object using your proxy credentials. You can optionally use filter_ip_locations to restrict proxy rotation to specific countries (e.g., ['de', 'us']) to reduce latency or bypass location restrictions.

from youtube_transcript_api import YouTubeTranscriptApi
from youtube_transcript_api.proxies import WebshareProxyConfig

ytt_api = YouTubeTranscriptApi(
    proxy_config=WebshareProxyConfig(
        proxy_username="<proxy-username>",
        proxy_password="<proxy-password>",
        filter_ip_locations=["de", "us"],
    )
)

ytt_api.fetch(video_id)

To discover which transcripts are available for a specific YouTube video, use the TranscriptListFetcher. This class handles the underlying HTTP requests and parsing of YouTube's internal data to provide a TranscriptList object.

TranscriptList can be iterated over to see all available transcripts (both manually created and automatically generated) or searched for specific languages.

The simplest way to retrieve a transcript is to use YouTubeTranscriptApi.fetch(video_id).

Important: Pass the video ID, not the full URL. For https://www.youtube.com/watch?v=12345, the ID is 12345.

By default, it attempts to fetch the English transcript. The method returns a FetchedTranscript object which is iterable, indexable, and provides a length.

from youtube_transcript_api import YouTubeTranscriptApi

ytt_api = YouTubeTranscriptApi()
fetched_transcript = ytt_api.fetch('12345')

# The object is iterable
for snippet in fetched_transcript:
    print(snippet.text)

# The object is indexable
last_snippet = fetched_transcript[-1]

# The object provides a length
snippet_count = len(fetched_transcript)

By default, YouTubeTranscriptApi creates its own requests.Session. You can pass your own Session object to the constructor via the http_client parameter. This allows you to:

• Share cookies between multiple YouTubeTranscriptApi instances.
• Set custom headers (e.g., Accept-Encoding).
• Specify custom SSL certificates via verify.

from requests import Session

http_client = Session()
http_client.headers.update({"Accept-Encoding": "gzip, deflate"})
http_client.verify = "/path/to/certfile"

ytt_api = YouTubeTranscriptApi(http_client=http_client)
ytt_api.fetch(video_id)

Use YouTubeTranscriptApi.list(video_id) to get a TranscriptList object. This object allows you to inspect available transcripts and filter them by language or type (manual vs. generated).

Available filtering methods on TranscriptList:

• find_transcript(languages): Finds a transcript matching the provided language list.
• find_manually_created_transcript(languages): Specifically searches for manually created transcripts.
• find_generated_transcript(languages): Specifically searches for automatically generated transcripts.

Each method returns a Transcript object which contains metadata and a .fetch() method to retrieve the actual data.