Tutorial de Python de Nodriver: Extracción de datos de navegadores de forma sigilosa, desde el primer script hasta la puesta en producción

• Nodriver se comunica directamente con el CDP; por sí solo, no elimina los riesgos relacionados con la IP, el TLS ni el comportamiento.
• Fija la versión. En la 0.50.3 + Chrome 154 (06/10/2026), select devuelve None en caso de fallo, wait_for genera un error y xpath falló con DOM.enable falta.
• Prefiero uc.loop() a asyncio.run para un apagado limpio; browser.stop() es «sync».
• Para trabajos en los que la discreción es importante, es preferible utilizar Chrome con interfaz gráfica bajo Xvfb: la versión sin interfaz gráfica sigue pudiendo anunciarse HeadlessChrome en el UA.
• La producción es donde fallan los rastreadores: contenedores, concurrencia limitada, reintentos, comprobaciones de IP de salida y validación de resultados.
• Asigna las esperas y acciones a los parámetros de la API del navegador (wait_for_css, wait_until, js_instructions, …) cuando el autoalojamiento se te quede pequeño.

Ruta clásica de Selenium:

Your script  →  WebDriver protocol  →  chromedriver  →  Chrome

Ruta de Nodriver:

Your script  →  Chrome DevTools Protocol (websockets)  →  Chrome

Al prescindir del binario del controlador, se eliminan los marcadores de automatización específicos de WebDriver y toda una clase de fallos debidos a discrepancias entre versiones. No convierte tu IP en residencial, ni hace que tu pila TLS sea única, ni que la sincronización de tus clics sea humana.

Nodriver es el sucesor asíncrono y centrado en CDP, procedente del mismo linaje de autores que undetected-chromedriver. El modelo pasa de «parchear el controlador» a «no utilizar nunca el controlador». Solo para navegadores de la familia Chromium; API exclusivamente asíncrona.

Comprobado en torno a la preparación de la publicación del 6 de octubre de 2026:

• Licencia: AGPL-3.0 en el paquete de PyPI que hemos instalado. Esto es importante para los servicios conectados a la red que modifican y ejecutan el código. Esto no constituye asesoramiento jurídico: consulta con un abogado la licencia AGPL si lanzas un SaaS basado en una bifurcación.
• Estructura de la API: solo asíncrona; navegadores de la familia Chromium.
• Mantenimiento: la última versión de PyPI comprobada para esta guía es la 0.50.3 (13 de mayo de 2026). Vuelve a comprobar las estrellas, los incidencias y las confirmaciones el día de la publicación antes de comprometerte con una plataforma a largo plazo.
• Cobertura de pruebas / clasificador alfa: PyPI sigue indicando «Estado de desarrollo :: 3 - Alfa». Prepárate para posibles fallos cuando Chrome cambie.
• Bifurcaciones: existen Zendriver y otras bifurcaciones de CDP si necesitas una estrategia de mantenimiento diferente; consulta la matriz de herramientas más adelante.

¿Necesitas compatibilidad con varios navegadores (Firefox/WebKit), API de sincronización o una licencia permisiva para un producto comercial sin análisis de la AGPL? Nodriver puede no ser la base adecuada.

python3 -m venv venv
source venv/bin/activate
pip install 'nodriver==0.50.3'

Lista de comprobación de la instalación:

1. Python ≥ 3.9.
2. Una instalación local de Chrome/Chromium (confirmar con google-chrome --version).
3. Dependencias de tiempo de ejecución obtenidas automáticamente: websockets>=14 , mss, deprecated.
4. No le pongas a tu script un nombre nodriver.py (ya que se superpone al paquete).
5. Prueba básica: abre una página pública y espera a que aparezca un selector (script más abajo).

Entorno de pruebas para este artículo: quotes.toscrape.com, un objetivo de demostración diferente al sitio web utilizado en varios tutoriales de la competencia.

# 01_first_scraper.py — verified 2026-10-06 on nodriver 0.50.3
import nodriver as uc

async def main():
    browser = None
    try:
        browser = await uc.start(headless=True)
        tab = await browser.get("https://quotes.toscrape.com/")
        await tab.select("div.quote", timeout=15)  # wait for state, not time
        quotes = await tab.select_all("div.quote")
        for q in quotes:
            text_el = await q.query_selector("span.text")
            author_el = await q.query_selector("small.author")
            print((text_el.text or "").strip(), "—", (author_el.text or "").strip())
    finally:
        if browser is not None:
            browser.stop()  # sync on 0.50.3 — do not await

if __name__ == "__main__":
    # Package README recommends uc.loop(); see event-loop notes below
    uc.loop().run_until_complete(main())

def attr_get(el, name: str):
    if el is None:
        return None
    attrs = el.attrs  # ContraDict in nodriver 0.50.3
    if attrs is None:
        return None
    try:
        return attrs.get(name)
    except Exception:
        try:
            return attrs[name]
        except Exception:
            return None

# Observed: element.text and element.text_all both return usable strings

Falló en Chrome 154 + nodriver 0.50.3 (06/10/2026) al llamar a DOM.enable. No se deben distribuir rastreadores que dependan de XPath en esta combinación sin una nueva verificación.

Esperar a un selector, texto o a que la red esté inactiva. Solucionado sleep es para casos excepcionales de depuración visual, no para rastreadores definitivos. Prefiere select / wait_for en lugar de tab.sleep en las rutas de producción.

Al hacer clic en «Siguiente», los identificadores de los elementos anteriores pueden desvincularse. Vuelve a consultar el control en cada intento; espera a que cambie la URL o a que aparezca un nuevo selector de contenido.

# Pagination retry pattern for quotes.toscrape.com-style next links
async def click_next_with_retry(tab, max_attempts=3) -> bool:
    for _ in range(max_attempts):
        next_link = await tab.select("li.next > a", timeout=5)
        if next_link is None:
            return False
        before = tab.url
        try:
            await next_link.click()
        except Exception:
            continue
        for _ in range(20):
            await tab.sleep(0.25)
            await tab.select("div.quote", timeout=2)
            if tab.url != before:
                return True
        if tab.url != before:
            return True
    return False

Páginas 1→2→3 avanzadas; los autores han cambiado según lo esperado.

Para las páginas sin un control de enlace «Siguiente», desplázate hasta una condición de parada: un marcador de fin, un recuento máximo o el número máximo de rondas.

async def scroll_until_plateau(tab, max_rounds=20):
    history = []
    plateau = 0
    for round_i in range(1, max_rounds + 1):
        items = await tab.select_all("div.item")
        count = len(items)
        end = await tab.query_selector("#end-marker")
        history.append(count)
        if end is not None:
            return {"reason": "end_marker", "count": count}
        if len(history) >= 2 and history[-1] == history[-2]:
            plateau += 1
        else:
            plateau = 0
        if plateau >= 2:
            return {"reason": "count_plateau", "count": count}
        await tab.evaluate("window.scrollTo(0, document.body.scrollHeight)")
        await tab.sleep(0.4)
    return {"reason": "max_rounds", "count": history[-1] if history else 0}

Se detuvo en end_marker en 40 elementos tras 4 rondas.

• Nueva pestaña/ventana: browser.get(url, new_tab=True) / new_window=True (API del paquete).
• tab.evaluate(expr) para sondas de desplazamiento/DOM: utiliza selectores siempre que puedas.
• Cookies: trata los archivos JAR como información confidencial; ocúltalos en los registros (nota de seguridad, no es un tutorial exhaustivo sobre cookies).
• Capturas de pantalla: await tab.save_screenshot(...) funcionaron en nuestra ejecución de diagnóstico.

Haz que el agente de usuario coincida con la versión de Chrome que realmente ejecutas. Una rotación aleatoria que no coincida con Chrome/154 (o lo que sea que ejecutes) es un indicio fácil de detectar. Es preferible utilizar una identidad de escritorio estable por cada perfil de trabajador.

Solo frente a páginas de diagnóstico públicas (bot.sannysoft.com; areyouheadless se devolvió un 502 en ambos modos):

El 154.0.0.0 textos mencionados son la forma abreviada del agente de usuario de Chrome, no un error tipográfico respecto a la 154.0.8037.57 . Nodriver puede borrar navigator.webdriver en ambos modos, mientras que el modo sin interfaz gráfica sigue identificándose a sí mismo a través de la cadena de agente de usuario. Eso por sí solo es suficiente para muchas comprobaciones sencillas.

En servidores Linux sin pantalla física:

# pattern
xvfb-run -a python your_scraper.py
# or export DISPLAY to a running Xvfb and start(headless=False)

Utiliza el modo sin interfaz gráfica para entornos de pruebas internos y CI. Utiliza el modo con interfaz gráfica + Xvfb cuando el destino detecte las cadenas de agente de usuario del modo sin interfaz gráfica.

No des por sentado que las configuraciones de Chrome son iguales a las de otros blogs. Antes de automatizar los muros de inicio de sesión detrás de un proxy, comprueba en tu versión de Chrome que la IP de salida del navegador sea la del proxy, y no la de tu host.

# Guard pattern — wire to your proxy stack; always assert exit IP before scraping
async def assert_exit_ip(tab, expected_subnet_prefix: str | None = None):
    tab2 = await tab.browser.get("https://httpbin.org/ip")  # or your IP echo
    await tab2.select("body", timeout=15)
    body = (await tab2.get_content()) if hasattr(tab2, "get_content") else None
    # parse JSON IP; compare to expected proxy IP; fail closed
    return body

Rechaza la tarea si la IP de salida observada es la de tu servidor del centro de datos. Realiza esta comprobación en producción incluso cuando el proxy «parezca estar configurado».

Cuando el problema sea la reputación de la IP o la afinidad con un país —y no la automatización del DOM—, enruta a través de proxies residenciales o traslada el trabajo del navegador a una solicitud de la API del navegador con country set.

La mayoría de los tutoriales se detienen antes de llegar a este punto. Aquí es donde los rastreadores fracasan.

# Outline only — adapt paths and package names for your base image
FROM python:3.13-slim-bookworm
RUN apt-get update && apt-get install -y --no-install-recommends \
    wget gnupg ca-certificates fonts-liberation xvfb \
    && install Google Chrome / Chromium per your distro docs \
    && useradd -m scraper
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
USER scraper
ENV DISPLAY=:99
CMD ["sh", "-c", "Xvfb :99 -screen 0 1920x1080x24 & python worker.py"]

Notas: ejecútalo sin privilegios de root; comprende los indicadores de sandbox de Chrome en contenedores restringidos; guarda los perfiles en un volumen en el que se pueda escribir si reutilizas cookies que te ha costado mucho conseguir; y oculta esas cookies en los registros.

Concurrencia limitada con un asyncio.Semaphore (o trabajadores en cola). Mide el consumo de memoria por navegador en páginas similares a las de producción en tu hardware.

• Tiempo de espera por navegación con wait_for / select límites.
• Clasifica los errores: tiempo de espera agotado, ventana vacía, página de verificación, fallo de Chrome.
• Reinicia el proceso del navegador tras errores de protocolo repetidos, no solo la pestaña.
• Limitar los reintentos con un retroceso aleatorio.

• Métricas: éxito / bloqueo / tiempo de espera / vacío por host.
• Captura de pantalla en caso de fallo en almacenamiento de objetos.
• Ocultación de datos en los registros: nombre de usuario/contraseña del proxy, Cookie encabezados y volcados de almacenamiento.

Un «éxito» de tipo HTTP en el navegador no es HTML utilizable. Detecta títulos de desafío, plantillas de aplicación vacías y selectores obligatorios que falten antes de escribir en el almacén. Combina esto con la mentalidad de validación de tu pila de scraping más amplia (evita que te bloqueen).

Ámbito (06-10-2026): solo páginas públicas de huellas digitales y diagnóstico. No se incluyen objetivos comerciales de Cloudflare ni DataDome (según la política editorial de este artículo).

Considera cualquier afirmación del tipo «nodriver elude X» que no vaya acompañada de una prueba con fecha y alcance definido como mera estrategia de marketing. Para objetivos reforzados, consulta también cómo eludir Cloudflare en la guía del producto.

Versiones comprobadas a través del índice PyPI el 6 de octubre de 2026. La postura de sigilo es cualitativa, no una puntuación.

Elección en función de las restricciones: licencia, motor del navegador, necesidades de sincronización y quién es responsable del tiempo de actividad.

• Pantallas / Xvfb / peculiaridades de la GPU en máquinas virtuales en la nube
• RAM y CPU por sesión simultánea de Chrome
• Proxies residenciales o móviles
• Tiempo de desarrollo para actualizaciones de Chrome y selectores defectuosos
• Gestión de bloqueos y servicio de guardia
• Almacenamiento de capturas de pantalla y supresión de datos personales
• Revisión del cumplimiento de la AGPL

Alójalo tú mismo cuando necesites sesiones interactivas prolongadas, extensiones personalizadas o una estrecha integración con redes internas. Cómpralo cuando quieras liberarte de las responsabilidades relacionadas con los SLA de solicitud/respuesta, la geolocalización y el mantenimiento del navegador.

La API del navegador es una llamada REST a https://api.webscrapingapi.com/v1—no un socket CDP en tiempo real (confirmación del producto). Nombres de parámetros verificados en los parámetros de la API el 6 de octubre de 2026:

Documentación: solicitud GET, renderización de JavaScript.

Si solo necesitas una instantánea HTML renderizada sin un script de interacción de varios pasos, empieza con la API de Scraper y el renderizado en JS. Pasa a la API del navegador cuando necesites acciones ordenadas, esperas de selectores, capturas de pantalla o reglas de extracción en una sola solicitud. Compara las opciones en «API de acceso web».

A partir de los errores que reproducimos el 6 de octubre de 2026:

Extrae solo páginas públicas elegibles, respeta los robots/Términos de servicio y la legislación aplicable, minimiza los datos personales y protege las credenciales. Lee «Datos web responsables». Para un contexto «headless» más amplio, consulta «Navegador headless en Python».

Una biblioteca asíncrona de Python que controla Chromium a través de CDP sin necesidad de Selenium ni Chromedriver. Esta guía utiliza la versión 0.50.3 (comprobada el 6 de octubre de 2026).

Selenium utiliza WebDriver + un binario de controlador. Undetected-chromedriver aplica parches a esa ruta. Nodriver omite WebDriver y se comunica con CDP de forma asíncrona.

Elimina algunas señales de automatización, pero no borra las fugas de IP, TLS, comportamiento o UA en modo headless. En nuestra prueba, navigator.webdriver no False, pero el modo sin interfaz gráfica seguía expuesto HeadlessChrome en el UA.

Sí, para el scraping funcional en nuestro entorno de pruebas. Para objetivos en los que el sigilo es importante, es preferible el modo con interfaz gráfica + Xvfb, según la diferencia en el UA que hemos medido.

Configura el proxy para tu versión de Chrome y, a continuación, comprueba siempre la IP de salida antes de iniciar el trabajo.

No generalices a partir de páginas de diagnóstico para productos comerciales de bots. Si utilizas verify_cf la versión 0.50.3, compruébalo en tus propios objetivos antes de confiar en ello.

Elige según la licencia, el motor del navegador, las necesidades de sincronización/asincronización y quién se encarga de las operaciones; consulta la matriz anterior. Playwright destaca en el ámbito multimotor; nodriver y zendriver están optimizados para un enfoque sigiloso de CDP con licencia AGPL; la API de navegador alojada es la mejor opción cuando no quieres flotas de Chrome.

Instala Chrome, ejecútalo en modo «headed» bajo Xvfb (o acepta las limitaciones del modo «headless»), como usuario no root y con trabajadores limitados. Utiliza el esquema del Dockerfile como punto de partida y valida la imagen en tu entorno.

Compruébalo en tu hardware y con las páginas de destino. No te fíes de las afirmaciones sobre concurrencia sin tus propias cifras.

El paquete que hemos instalado está bajo licencia AGPL-3.0. Consulta con un asesor legal antes de integrarlo en un servicio de red. Esto no constituye asesoramiento jurídico.

Cuando quieras esperas/acciones/datos geográficos REST sin tener que ejecutar Chrome, o cuando los costes de proxy y mantenimiento sean predominantes. Convierte tus esperas de nodriver en wait_for_css / js_instructions y compara una solicitud.

Elige una página que tu script de nodriver ya gestione y envíala mediante una única solicitud de la API del navegador con wait_for_css (y js_instructions si te desplazas o haces clic). Compara el tiempo de desarrollo, los modos de fallo y el formato de los resultados. Para grandes volúmenes, datos geográficos o entregas gestionadas, ponte en contacto con el equipo de WebScrapingAPI.