selenium-captcha 1.0.0

Simple and lightweight Python SDK for Selenium that facilitates the automation of text captcha and reCaptcha in enterprise automation workflows using Death By Captcha.

DOM Tasks

Automate text CAPTCHA and reCAPTCHA in Selenium with Python.

result = await solver.solve(
    RecaptchaChallenge(
        page=driver,
    )
)

✔ No polling loops

✔ No API requests

✔ No token injection

✔ No balance fetching

✔ No manual retry logic

Getting Started

DOM Tasks 'selenium-captcha' integrates with DeathByCaptcha to solve text CAPTCHAs and reCAPTCHA.

Before you begin:

👉 Create a DeathByCaptcha account. When you're ready to solve captchas, simply add credits to it; packages start at just $5.

The examples throughout this documentation use DeathByCaptcha and require the API credentials you'll obtain after registering.

Install the package:

pip install selenium-captcha

Install Selenium:

pip install selenium

If you're storing credentials as environment variables:

pip install python-dotenv

🚀 Start Here

Don't scroll yet.

Choose the guide that matches your use case.

Step 1 - I want to...

• 👉 Solve a text captcha
• 👉 Solve a reCAPTCHA v2

Each guide walks through authentication, solving the challenge, viewing the result, and handling incorrect captchas.

---

Solving Text captcha

Step 2 - I want to authenticate with...

• 👉 DBC Username & Password
• 👉 DBC Authtoken (2FA)

Username and password authentication

Authenticate using your DeathByCaptcha account credentials.

import os

from captcha_solver import (
    CaptchaSolver,
    CaptchaSolverOptions,
    Credentials,
)

solver = CaptchaSolver(
    CaptchaSolverOptions(
        auth=Credentials(
            username=os.getenv("DBC_USERNAME"),
            password=os.getenv("DBC_PASSWORD"),
        )
    )
)

Credentials: Authenticates using your DeathByCaptcha username and password.

username: Your DeathByCaptcha account username.

password: Your DeathByCaptcha account password.

We recommend storing credentials as environment variables.

Step 3 - Solve captcha

• 👉 Solve text captcha

---

Authtoken authentication

a) Setting up 2FA (authtoken) with DeathByCaptcha

1. Log in to your account
2. Go to User Settings at the bottom of the page
3. Click on Authentication options
4. Check the box "Enable this to use 2FA authentication" and click on SUBMIT
5. Download Google Authenticator app, open it and click on the '+' button to add a new entry.
6. Scan the QR code with your phone through the app and insert the code from the app into 'Verification code' field on the site.
7. Copy and save your "Authentication Token" as an environment variable in your code and finally check the box "Enable this to use the token instead of User/Password combination" on the site. Authentication Token is ~156 characters long.

Sample token:

CQ6dd4DzLk5y830M2S16TnNEAqetNp2VmAPPx6CjM5wxRYpS0zm0CTMH38iBKfC3qf4tB9d2XIpzI184ZJv0G2RMUUcHi60372MRxUkE5A71bDopA3aQum2029LlLwX4R61hwr7fR51p6zRADdhT9u07e9v6

b) Initialize the solver:

import os

from captcha_solver import (
    CaptchaSolver,
    CaptchaSolverOptions,
    AuthToken,
)

solver = CaptchaSolver(
    CaptchaSolverOptions(
        auth=AuthToken(
            authtoken=os.getenv("DBC_AUTHTOKEN"),
        )
    )
)

AuthToken: Authenticates using your DeathByCaptcha Authentication Token.

authtoken: Your DeathByCaptcha Authentication Token.

We recommend storing it as an environment variable instead of hardcoding it into your application.

Solving Text Captchas

Use the solve() method to solve the challenge currently displayed on the page.

result = await solver.solve(
    ImageChallenge(
        page=driver,
        captcha=captcha,
        input=input_box,
    )
)

ImageChallenge: Represents an image CAPTCHA challenge.

page: A Selenium Webdriver instance.

Example:

driver = webdriver.Chrome()

captcha: A Selenium WebElement pointing to the CAPTCHA image.

Supported elements include:

• <img>
• <canvas>
• <svg>
• Container elements wrapping the CAPTCHA

Example:

captcha = driver.find_element(
    By.ID,
    "demoCaptcha_CaptchaImage",
)

input: A Selenium WebElement representing the textbox where the solved CAPTCHA should be entered.

Example:

input_box = driver.find_element(
    By.ID,
    "captchaCode",
)

Captcha solution metadata

The solve() method returns a SolveResult.

result = await solver.solve(
    ImageChallenge(
        page=driver,
        captcha=captcha,
        input=input_box,
    )
)

print(result)

Example output:

SolveResult(
    success=True,
    challenge="image",
    duration=4124,
    id="235368206",
    balance=10.081007,
)

The returned object contains:

success: Whether the operation completed successfully. If your target website still rejects the submitted CAPTCHA after automation continues, you should report it using report().

challenge: The type of challenge that was solved.

duration: Total execution time in milliseconds.

id: The CAPTCHA identifier assigned by DeathByCaptcha.

balance: Your remaining DeathByCaptcha balance after solving the challenge.

Reporting incorrect captchas:

Incorrect solutions can be reported to DeathByCaptcha so your account is credited appropriately.

result = await solver.solve(
    ImageChallenge(
        page=driver,
        captcha=captcha,
        input=input_box,
    )
)

await solver.report(result.id)

Your automation should determine whether the CAPTCHA was accepted by the target website.

For example, your application may:

Detect a validation message. Wait for a successful page navigation. Solve the captcha with the solve() function. Submit the form. Inspect for a warning if captcha was incorrect.

If the CAPTCHA was solved incorrectly, report it using:

await solver.report(result.id)

Please use this feature responsibly. Excessive reporting of correctly solved CAPTCHAs may result in account restrictions.

Text captcha full code example

Install dependencies:

pip install selenium
pip install python-dotenv
pip install selenium-captcha

import asyncio
import os

from dotenv import load_dotenv

from selenium import webdriver
from selenium.webdriver.common.by import By

from captcha_solver import (
    CaptchaSolver,
    CaptchaSolverOptions,
    Credentials,
    ImageChallenge,
)

load_dotenv()

async def main():

    driver = webdriver.Chrome()

    try:

        driver.get(
            "https://captcha.com/demos/features/captcha-demo.aspx"
        )

        captcha = driver.find_element(
            By.ID,
            "demoCaptcha_CaptchaImage",
        )

        input_box = driver.find_element(
            By.ID,
            "captchaCode",
        )

        async with CaptchaSolver(
            CaptchaSolverOptions(
                auth=Credentials(
                    username=os.getenv("DBC_USERNAME"),
                    password=os.getenv("DBC_PASSWORD"),
                )
            )
        ) as solver:

            result = await solver.solve(
                ImageChallenge(
                    page=driver,
                    captcha=captcha,
                    input=input_box,
                )
            )

            print(result)

            # await solver.report(result.id)

        driver.find_element(
            By.ID,
            "validateCaptchaButton",
        ).click()

        await asyncio.sleep(5)

    finally:
        driver.quit()

asyncio.run(main())

Next Step — Error handling:

• 👉 Continue to the Error Handling section after the reCAPTCHA guide

Solving reCAPTCHA v2

Step 2 - I want to authenticate with...

• 👉 DBC Username & Password
• 👉 DBC Authtoken (2FA)

Username password authentication

Authenticate using your DeathByCaptcha account credentials.

import os

from captcha_solver import (
    CaptchaSolver,
    CaptchaSolverOptions,
    Credentials,
)

solver = CaptchaSolver(
    CaptchaSolverOptions(
        auth=Credentials(
            username=os.getenv("DBC_USERNAME"),
            password=os.getenv("DBC_PASSWORD"),
        )
    )
)

Credentials: Authenticate using your DeathByCaptcha username and password.

username: Your DeathByCaptcha account username.

password: Your DeathByCaptcha account password.

We recommend storing credentials as environment variables.

Step 3 - Solve reCAPTCHAS

• 👉 Automate reCAPTCHA v2

---

Authtoken authentication method

a) Setting up 2FA (authtoken) with DeathByCaptcha

1. Log in to your account
2. Go to User Settings at the bottom of the page
3. Click on Authentication options
4. Check the box "Enable this to use 2FA authentication" and click on SUBMIT
5. Download Google Authenticator app, open it and click on the '+' button to add a new entry.
6. Scan the QR code with your phone through the app and insert the code from the app into 'Verification code' field on the site.
7. Copy and save your "Authentication Token" as an environment variable in your code and finally check the box "Enable this to use the token instead of User/Password combination" on the site. Authentication Token is ~156 characters long.

Sample token:

CQ6dd4DzLk5y830M2S16TnNEAqetNp2VmAPPx6CjM5wxRYpS0zm0CTMH38iBKfC3qf4tB9d2XIpzI184ZJv0G2RMUUcHi60372MRxUkE5A71bDopA3aQum2029LlLwX4R61hwr7fR51p6zRADdhT9u07e9v6

b) Initialize solver with token created:

import os

from captcha_solver import (
    CaptchaSolver,
    CaptchaSolverOptions,
    AuthToken,
)

solver = CaptchaSolver(
    CaptchaSolverOptions(
        auth=AuthToken(
            authtoken=os.getenv("DBC_AUTHTOKEN"),
        )
    )
)

AuthToken: Authenticate using your DeathByCaptcha Authentication Token.

authtoken: Your DeathByCaptcha Authentication Token.

We recommend storing it as an environment variable instead of hardcoding it.

Solving reCAPTCHAs v2

result = await solver.solve(
    RecaptchaChallenge(
        page=driver,
        # proxy="http://username:[e-mail]"
    )
)

RecaptchaChallenge: Represents a Google reCAPTCHA v2 challenge.

page: A Selenium WebDriver instance.

Example:

driver = webdriver.Chrome()

proxy: (Optional) An HTTP proxy string.

Example:

proxy="http://username:[e-mail]"

If omitted, the current network connection is used.

---

Captcha solution metadata

The solve() method returns a SolveResult.

result = await solver.solve(
    RecaptchaChallenge(
        page=driver,
    )
)

print(result)

Example output:

SolveResult(
    success=True,
    challenge="recaptcha",
    duration=14124,
    id="235368206",
    balance=10.091007,
)

The returned object contains:

success: Whether the operation completed successfully.

challenge: The challenge type that was solved.

duration: Total execution time in milliseconds.

id: DeathByCaptcha challenge identifier.

balance: Your remaining DeathByCaptcha account balance after solving the challenge.

ReCAPTCHA full code example

Install dependencies:

pip install selenium
pip install python-dotenv
pip install selenium-captcha

import asyncio
import os

from dotenv import load_dotenv

from selenium import webdriver
from selenium.webdriver.common.by import By

from captcha_solver import (
    CaptchaSolver,
    CaptchaSolverOptions,
    Credentials,
    RecaptchaChallenge,
)

load_dotenv()

async def main():

    driver = webdriver.Chrome()

    try:

        driver.get(
            "https://www.google.com/recaptcha/api2/demo"
        )

        async with CaptchaSolver(
            CaptchaSolverOptions(
                auth=Credentials(
                    username=os.getenv("DBC_USERNAME"),
                    password=os.getenv("DBC_PASSWORD"),
                )
            )
        ) as solver:

            result = await solver.solve(
                RecaptchaChallenge(
                    page=driver,
                )
            )

            print(result)

        driver.find_element(
            By.ID,
            "recaptcha-demo-submit",
        ).click()

        await asyncio.sleep(5)

    finally:
        driver.quit()

asyncio.run(main())

Error Handling

The SDK throws typed errors instead of generic Error objects.

Possible Errors

Error	Description
NetworkError	Network error, conexion lost.
TimeoutError	The operation exceeded the configured timeout.
CaptchaSolverError	The provider returned an error.

Design Principles

DOM Tasks follows a minimal design philosophy.

• You own the browser.

• You own the Selenium WebDriver.

• You own the automation workflow.

• The SDK performs one operation and immediately returns control.

• The SDK never creates browser instances.

• The SDK never manages browser lifecycle.

• The SDK never hides Selenium APIs.

This allows the SDK to integrate naturally into existing Selenium automation without imposing its own framework or execution model.

Why DOM Tasks?

DOM Tasks is designed to feel like a native extension to SeleniumBase rather than another automation framework.

Instead of forcing you to learn a new API, it integrates directly into your existing workflow.

result = await solver.solve(
    RecaptchaChallenge(
        page=driver,
    )
)

Everything else remains under your control.

• Use your own waits.
• Use your own logging.
• Use your own retry strategy.
• Use your own browser configuration.
• Use your own proxies.
• Continue using SeleniumBase exactly as you already do.

The SDK focuses on solving CAPTCHAs and immediately returns control back to your automation.

---

RESPONSIBLE USE

We encourage the responsible and ethical use of automation technologies and does not endorse or encourage the misuse of this software to violate applicable laws, contractual obligations, or the rights of others.

License

Copyright © 2026 DOM Tasks.

LICENSE GRANT

Subject to this License, you are granted permission to:

✓ Install and use this software.

✓ Use this software in personal projects and in commercial or internal business applications developed by you or your organization.

✓ Modify this software solely for your own internal use.

You may NOT:

✗ Redistribute this software, whether modified or unmodified.

✗ Publish or make available modified versions of this software to any third party.

✗ Sell, sublicense, rent, lease, assign, or otherwise transfer this software or any modified version of it.

✗ Remove, alter, or obscure any copyright notices, trademarks, branding, attribution, or license notices contained in the software.

✗ Represent modified versions as the original software.

✗ Use the software in violation of applicable laws.

✗ Use this software or any substantial portion of it to develop, distribute, or commercialize a competing software library, SDK, or similar product.

OWNERSHIP

No ownership rights are transferred under this License. Ownership of the software and all intellectual property rights remain with the copyright holder.

All rights not expressly granted under this License are reserved by the copyright holder.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND...

# Disclaimer: 

Disclaimer:

This is an unofficial package and it is not affiliated or endorsed by the maintainers of Selenium, package name indicates compatibility.