Step-by-Step Setup Guide
Prerequisites
| Requirement | Minimum Version |
|---|---|
| Python | 3.8 |
| pip | 21.0 |
Step 1 — Clone or Download the Project
If you have Git installed:
git clone https://github.com/your-username/youtube-transcript-fetcher.git
cd youtube-transcript-fetcher
Or download and unzip the archive, then open a terminal inside the folder.
Step 2 — Create a Virtual Environment (Recommended)
macOS / Linux
python3 -m venv .venv
source .venv/bin/activate
Windows (Command Prompt)
python -m venv .venv
.venv\Scripts\activate.bat
Windows (PowerShell)
python -m venv .venv
.venv\Scripts\Activate.ps1
You should see (.venv) at the start of your terminal prompt when the environment is active.
Step 3 — Install Dependencies
pip install -r requirements.txt
Verify the install:
pip show youtube-transcript-api
Step 4 — Run the Script
Basic usage — print transcript to terminal
python main.py "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
Save to a file
python main.py "https://youtu.be/dQw4w9WgXcQ" -o transcript.txt
Export as SRT subtitles
python main.py dQw4w9WgXcQ -f srt -o transcript.srt
Export as JSON
python main.py dQw4w9WgXcQ -f json -o transcript.json
Include timestamps in plain-text output
python main.py dQw4w9WgXcQ -t
Request a specific language
python main.py dQw4w9WgXcQ -l es # Spanish
python main.py dQw4w9WgXcQ -l ja ko en # Japanese, then Korean, then English
List all available languages for a video
python main.py dQw4w9WgXcQ --list
Batch — multiple videos saved to a directory
python main.py VIDEO_ID_1 VIDEO_ID_2 VIDEO_ID_3 -o ./transcripts/
Step 5 — Deactivate the Virtual Environment (When Done)
deactivate
Troubleshooting
| Error | Cause | Fix |
|---|---|---|
TranscriptsDisabled |
The video owner turned off transcripts | Nothing can be done; try another video |
VideoUnavailable |
Video is private, deleted, or region-locked | Check the URL; use a VPN if region-locked |
NoTranscriptFound |
Requested language does not exist | Run --list and pick an available language |
ModuleNotFoundError |
Dependencies not installed | Run pip install -r requirements.txt |
| Empty output | Video has no speech or very short content | Confirm the video has captions enabled |
Input Formats Accepted
All of the following point to the same video and are equally valid input:
https://www.youtube.com/watch?v=dQw4w9WgXcQ
https://youtu.be/dQw4w9WgXcQ
https://www.youtube.com/shorts/dQw4w9WgXcQ
https://www.youtube.com/embed/dQw4w9WgXcQ
dQw4w9WgXcQ
Output Formats
| Flag | Format | Best For |
|---|---|---|
text (default) |
Plain text, one line per caption segment | Reading, summarization, NLP |
json |
JSON array with text, start, duration fields |
Programmatic processing |
srt |
SubRip subtitle format | Video players, Premiere, DaVinci |
vtt |
WebVTT subtitle format | HTML5 video, browsers |