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 · 16 comments

Handle youtube CAPTCHAs (402 errors) gracefully #154

phihag opened this issue Sep 13, 2011 · 16 comments


Copy link

@phihag 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 /
Copy link
Contributor Author

@phihag 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

Copy link

@skakri 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.

Copy link

@Strolls 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.

Copy link

@vanilla38 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

Copy link

@Strolls 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.

Copy link

@twqqis 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...

Copy link

@bassrock 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?

Copy link

@ghost ghost 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.

Copy link

@EthanSbbn EthanSbbn commented Feb 22, 2013

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

Copy link

@ghost ghost 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:

Copy link

@ivan 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.

Copy link

@manrodriguezf manrodriguezf commented Jun 2, 2015

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

--sleep-interval SECONDS

cheers everyone

Copy link

@aki263 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.

Copy link

@J0WI J0WI commented Jan 8, 2020

The featured pages of channels are currently not affected by captchas. Have you thought of a way to extract the video url from there and bypassing CAPTCHAs?

joedborg referenced this issue in joedborg/youtube-dl Nov 17, 2020
[pull] master from rg3:master
Copy link

@schnusch schnusch commented Jan 26, 2021

I'm not sure if this is the right issue for a discussion about CAPTCHA handling in general. This would allow youtube-dl to also handle hosts that require solving a CAPTCHA before a video link can be obtained.

I recently tried to to handle reCAPTCHAs by displaying them to the user embedded in a custom website to extract the response. Because reCAPTCHA verifies the host of the page it is embedded in, and I assume hCaptcha does so too, the location needs to be faked. This resulted in a simple tool utilizing WebKitGTK (see which uses WebKit's webkit_web_view_load_html to fake the location. I just now discovered webRequest.filterResponseData(), which could be used in a web extension, but seems to be only available in Firefox. This would allow to display a CAPTCHA in a custom page too.

Is there any interest of handling CAPTCHAs, perhaps in an external tool, that is invoked by youtube-dl when available on the system?

Copy link

@Nottt Nottt commented Feb 8, 2021

Just use this service

Then let people submit their own login to it if they want to bypass captchas

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
None yet
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet