Registry / http-networking / youtube-transcript-api

youtube-transcript-api

library1.2.4pypypi✓ verified 24d ago

This is a Python API that allows you to retrieve transcripts and subtitles for a given YouTube video. It supports both manually created and automatically generated subtitles, as well as subtitle translation. Unlike older solutions, it does not require a headless browser. The library is actively maintained, currently at version 1.2.4, and receives regular updates to address YouTube's API changes.

http-networking ai-ml

pip install youtube-transcript-api

github ↗package ↗

INSTALL

IMPORT

SIG · YOUTUBE-TRANSCRIPT

youtube-transcript-api

http-networkingpythonv1.2.4

Install

2.5s avg

Import

480ms

Disk

22MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.2.4 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.496s · 23.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.5s · import 0.464s · 24MB

22MB installed

● package 22MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

YouTubeTranscriptApi

✓ from youtube_transcript_api import YouTubeTranscriptApi

✗ from youtube_transcript_api import YouTubeTranscriptApi YouTubeTranscriptApi.get_transcript(video_id)

As of v1.2.0, the static methods `get_transcript`, `get_transcripts`, and `list_transcripts` were removed. Instantiate `YouTubeTranscriptApi` and use instance methods like `fetch`.

NoTranscriptFound

✓ from youtube_transcript_api import NoTranscriptFound

This exception is raised if no transcript can be found for the given video ID.

TranscriptsDisabled

✓ from youtube_transcript_api import TranscriptsDisabled

This exception is raised if transcripts are explicitly disabled for the video.

NoManualTranscriptFound

✓ from youtube_transcript_api import NoManualTranscriptFound

This exception is raised if no manually created transcript is available for the video in the requested language(s).

IpBlocked

✓ from youtube_transcript_api import IpBlocked

This exception indicates that the request was blocked, often due to aggressive rate limiting or IP blocking by YouTube, especially from cloud providers.

This quickstart demonstrates how to fetch a transcript for a given YouTube video ID using the `YouTubeTranscriptApi` client. It includes error handling for common issues like missing or disabled transcripts and IP blocking. The example retrieves the 'Never Gonna Give You Up' transcript and prints its beginning.

from youtube_transcript_api import YouTubeTranscriptApi, NoTranscriptFound, TranscriptsDisabled, IpBlocked video_id = "_dQ8wY76uI8" # Example: 'Never Gonna Give You Up' by Rick Astley try: # Instantiate the API client ytt_api = YouTubeTranscriptApi() # Fetch the transcript for the video # By default, it attempts to get English. You can specify languages=['de', 'en'] for priority. transcript = ytt_api.fetch(video_id) # Print the full transcript text full_text = " ".join([item['text'] for item in transcript]) print(f"Transcript for video ID {video_id}:\n{full_text[:500]}...") # You can also list available transcripts and their languages # transcript_list = ytt_api.list_transcripts(video_id) # for t in transcript_list: # print(f"Available transcript: {t.language} ({'generated' if t.is_generated else 'manual'})") except NoTranscriptFound: print(f"No transcript found for video ID: {video_id}") except TranscriptsDisabled: print(f"Transcripts are disabled for video ID: {video_id}") except IpBlocked: print(f"Your IP was blocked by YouTube. Consider using a proxy.") except Exception as e: print(f"An unexpected error occurred: {e}")

Debug

Known issues

breakingThe static methods `YouTubeTranscriptApi.get_transcript`, `YouTubeTranscriptApi.get_transcripts`, and `YouTubeTranscriptApi.list_transcripts` were removed in `v1.2.0`. These methods were previously deprecated in `v1.0.0`.

fix

Instead of calling static methods, instantiate the `YouTubeTranscriptApi` object and use its instance methods like `ytt_api.fetch(video_id)` or `ytt_api.list_transcripts(video_id)`.

affects: >=1.2.0

breakingIn `v1.1.0`, the library refactored caption retrieval from scraping the `/watch` HTML to fetching from the Innertube API. This change initially did not support authentication, potentially causing issues for users relying on authenticated requests.

fix

Ensure your environment and usage patterns are compatible with the Innertube API approach. Monitor for `PoTokenRequired` exceptions, which may indicate new authentication requirements, and report them to the library maintainers.

affects: >=1.1.0

gotchaYouTube frequently blocks requests from known cloud provider IPs or if a high volume of requests originates from a single IP. This can lead to `IpBlocked` exceptions.

fix

For heavy usage or deployment on cloud platforms, consider using rotating proxy services (e.g., Webshare) configured with the `WebshareProxyConfig` class when initializing `YouTubeTranscriptApi`.

affects: All

gotchaEnsure you pass only the YouTube video ID, not the full video URL, to the API methods. For example, for `https://www.youtube.com/watch?v=VIDEO_ID`, the video ID is `VIDEO_ID`.

fix

Extract the video ID from the URL before passing it to `fetch` or `list_transcripts`.

affects: All

gotchaIf you encounter `NoTranscriptFound` or `TranscriptsDisabled` exceptions, it means the video either genuinely lacks captions or has them explicitly turned off by the uploader. Some automatically generated captions may also not be available.

fix

Handle these exceptions gracefully in your code. You can use `list_transcripts` to check for available languages before attempting to fetch a specific one.

affects: All

Errors

Common errors & fixes

NoTranscriptFound: Could not find any transcripts for the video <video_id>.

This error occurs when YouTube does not provide any transcripts (manual or auto-generated) for the specified video in the requested language(s).

fix

Verify that transcripts are available for the video on YouTube. You can try requesting different languages, or catch this exception in your code to handle cases where transcripts are legitimately absent.

VideoUnavailable: The video <video_id> is unavailable.

The specified YouTube video is private, deleted, age-restricted, or otherwise not publicly accessible through the API.

fix

Ensure that the video ID corresponds to a publicly available, non-restricted YouTube video. Implement error handling to gracefully manage unavailable videos.

ModuleNotFoundError: No module named 'youtube_transcript_api'

The `youtube-transcript-api` library has not been installed in the Python environment where the script is being executed.

fix

Install the library using pip: `pip install youtube-transcript-api`

InvalidVideoId: <video_id> is no valid YouTube video ID.

The string provided as a video ID does not match the expected 11-character format of a YouTube video ID, or it might be a full URL instead of just the ID.

fix

Provide only the 11-character YouTube video ID. If you have a full YouTube URL, extract the ID part (e.g., 'dQw4w9WgXcQ' from 'https://www.youtube.com/watch?v=dQw4w9WgXcQ').

Upgrade

Version history

1.2.4latest on PyPI · released Jan 29, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

96 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/jdepoix/youtube-transcript-api ↗

packagehttps://pypi.org/project/youtube-transcript-api/ ↗