Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Handle youtube CAPTCHAs (402 errors) gracefully #154

phihag opened this Issue Sep 13, 2011 · 13 comments


None yet
Copy link

phihag commented Sep 13, 2011

Upon encountering a 402 error, youtube-dl should:

  • By default, throw out an error ("Due to high usage, youtube requires a CAPTCHA to be solved. Specify the --captcha-solver or --captcha-interactive option to solve the CAPTCHA.")
  • If the --captcha-solver has been specified, execute the specified program. Write the CAPTCHA image to its stdin and read its stdout. Enter the trimmed stdout as the CAPTCHA and continue downloading.
  • If the --captcha-interactive option has be been specified, download the file to a temporary location and call ['xdg-open', 'tmpfile']. If this fails, abort with an error message. Otherwise, call raw_input() and ask for a solution for the CAPTCHA.

Implementation notes:

  • This is requires an option captcha-solver. For the moment, I'm not sure whether it should be a Python callback(Fits better in a library) or a string(Allows serialization of options).
  • It will be hard to test. I can have a process downloading 24/7 from a high-bandwidth server until it encounters this problem, but there should be a nicer way to get youtube to present CAPTCHAs
  • Afterwards, update the FAQ / documentation /

This comment has been minimized.

Copy link
Collaborator Author

phihag commented Oct 11, 2011

It would be great if someone could provide a pcap dump that contains

  • youtube-dl encountering the error
  • A browser (like Firefox) encountering the error
  • Solving the CAPTCHA in Firefox

This comment has been minimized.

Copy link

skakri commented Mar 3, 2012

Hi phihag, here is the dump -

Steps made:

So basically you'd have to forcibly save cookie jar and save passed cookies (use_hitbox, goojf, I'm not sure about VISITOR_INFO1_LIVE) before and after authentication (only captcha filling should be done in a real browser), parse returned html page (goes via 302 redirect) and get iframe location. This URL should be passed to console, so user can click or copy-paste in browser. User fills the captcha in his browser, copies returned hash and pastes in youtube-dl. And again, same as step one - save cookies and afterwards - retry downloading.

Maybe you should take a look at Mechanize - - unfortunately I'm not familiar with Python, but WWW::Mechanize works really well for Perl.


This comment has been minimized.

Copy link

Strolls commented May 16, 2012

The most important thing IMO is to give a different exit code if this 402 error is returned. I'm pretty sure this is what's requested in closed issue 144.

For the benefit of Google, this is presently the best (??) way to catch 402 errors:

error=$(youtube-dl -q "$url" 2>&1)
if [ "$?" -eq 0 ] ; then
  echo "video downloaded ok!"
  case "$error" in
    (*404*) echo "Error - video deleted" ;;
    (*402*) echo "Error - retrying too fast" ;;

Obviously, you can put some other stuff - to handle what to actually do in the case of a successful download or error - next to the appropriate echo statement. This will probably involve sleeping before retrying the download.

For the record, it doesn't require a fast box connected 24/7 to produce this error - I can reproduce using youtube-dl --write-info-json --skip-download -q "$url" (i.e. only getting the metadata about the videos) with a slow box on a home connection and only a hundred or two videos. This does appear to vary - some days this week YouTube appears to have let me get away with more than on others.


This comment has been minimized.

Copy link

vanilla38 commented Jul 1, 2012

Hey i'm actually working on a project mainly depending on youtube-dl and I'm sure I'll encounter this error, does someone found a way to bypass or solve this problem ?
I got an idea but i'm not sure if it's possible:

  1. send shell cmd by php an launch youtube-dl
  2. if error 402 send captcha image and input to php
  3. write captcha in the website and send it to linux
    4)continue to DL

This comment has been minimized.

Copy link

Strolls commented Jul 1, 2012

I don't really think this is the place to expand much on my comments above.

Whilst I hoped to help people who are encountering this problem, this is a bug report for youtube-dl, not a homework assistance forum.

Once the user fills in a captcha, the IP address is once again allowed to download.

However, filling in a captcha sets a cookie in the browser - this session is given freer access to YouTube than other sessions from the same IP.

Even with another session allowed access, it is easy for youtube-dl to once again exceed permitted downloads (and once again hit the 402 error).

youtube-dl does not have any way to tell you what captcha it wants you to solve, thus also no way for you to return the result of a captcha.

If you can have your PHP program flush the cookies from a browser and open a new browser on the same machine, then that will work.

The easiest way I have found to solve this is to build a dynamic delay - when you get a 402 error, just wait for some time before trying again. When you get multiple successful downloads, decrease the delay. This means the downloads are slower, but no human interaction is required. If you fill in a captcha, then you'll need to fill in another one within a couple of downloads; if you just wait some time (or take it easy for some time) then you can eventually resume again at a reasonable speed.

I am not going to tell you any more of what I know of the parameters of YouTube's rate limiting. As soon as they become publicly disseminated, YouTube will tighten their restrictions further.

If you need further assistance, post a question in an appropriate forum and message or email me, so that I can answer it there in public.


This comment has been minimized.

Copy link

twqqis commented Oct 9, 2012

I was going to suggest the dynamic delay, but then noticed Strolls got it down quite nicely. Think it'll be a simple solution to try and test; at least taking the human interaction out of the equation - say when leaving the computer unattended for some time...


This comment has been minimized.

Copy link

bassrock commented Oct 20, 2012

Would it be possible to implement something like this:

Or this:

They are both written in python and may be able to be included easily?


This comment has been minimized.

Copy link

jasonrwalters commented Feb 19, 2013

What about adding OAuth 2 support so we can authorize our apps using this library against YouTube? This would solve the issue as far as I can tell.


This comment has been minimized.

Copy link

EthanSbbn commented Feb 22, 2013

@jasonrwalters in what would consist your solution? Can you explain please?


This comment has been minimized.

Copy link

jasonrwalters commented Mar 16, 2013

Actually, are we able to place our developer API key in our calls? If that's not a feature it should be. But if the captcha occurs because you're improperly flagged then you need to contact Google, and just write something to handle the event yourself.

See Google docs:


This comment has been minimized.

Copy link

ivan commented Sep 3, 2013

I had CAPTCHA issues frequently when re-grabbing entire channels. I implemented some hacks to (1) avoid hitting YouTube for videos I've already downloaded, and (2) wait 1 sec between HTTP requests: - and I haven't had problems since.


This comment has been minimized.

Copy link

manrodriguezf commented Jun 2, 2015

In the docs there's an option for that now:

--sleep-interval SECONDS

cheers everyone


This comment has been minimized.

Copy link

aki263 commented Aug 16, 2017

I would suggest adding auto captcha solver from or some other website because if you are using this to download vids for personal use than you won't encounter captcha but if you are doing like making a website that downloads youtube vids, than you need a service. So a auto captcha solver service is best option.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.