QGIS4 ya está aquí

13/05/2026 · Eduard Kazakov, Claudio Matko

Los desarrolladores de plugins tienen dos cosas que solucionar

Puntos clave

QGIS 4.0 “Norrköping” se lanzó el 6 de marzo de 2026 e introduce dos cambios importantes para cualquiera que mantenga un complemento en QGIS.
El primero es el cambio de Qt5 a Qt6, el marco de trabajo de interfaz gráfica de usuario sobre el que se basa QGIS, rompe la compatibilidad con la mayoría de los complementos existentes.
El segundo es un nuevo sistema de escaneo de seguridad que revisa cada complemento antes de que se publique en el repositorio.
Ambos cambios requieren que ejecutes tu complemento y verifiques su comportamiento, no solo que superes las comprobaciones automatizadas.
QGIS DevTools conecta VS Code a una sesión de QGIS en ejecución para que puedas hacer precisamente eso, pausar la ejecución en cualquier momento, ver qué está sucediendo dentro de tu complemento y detectar problemas antes de que lo hagan tus usuarios.

Introducción

QGIS 4.0 “Norrköping” se lanzó el 6 de marzo de 2026, siendo la primera actualización importante en aproximadamente ocho años, desde QGIS 3.0 “Girona” en 2018. Para la mayoría de los usuarios, la interfaz es prácticamente idéntica. Sin embargo, para los desarrolladores de complementos, esta actualización trae consigo dos conjuntos de requisitos distintos que se implementaron simultáneamente.

Este artículo analiza ambos aspectos e indica como se integra QGIS DevTools.

Primer cambio: Qt6

QGIS está construido sobre un marco de software llamado Qt (“cute”), el cual gestiona todo, desde el diseño de las ventanas y los botones hasta la comunicación de la aplicación con Python. QGIS ha estado funcionando con Qt versión 5 desde 2016. QGIS 4 pasa a utilizar Qt versión 6.

Las versiones 5 y 6 no son totalmente compatibles. Es muy poco probable que los complementos desarrollados para Qt5 funcionen en QGIS 4. Este es el cambio más importante para los desarrolladores de complementos, aunque para muchos ya es información conocida.

El proyecto QGIS ha hecho mucho para facilitar la transición. La versión QGIS 3 LTR se extendió para dar a los desarrolladores más tiempo. Una guía de migración oficial y un script de conversión ( pyqt5_to_pyqt6.py ) están disponibles para gestionar automáticamente la mayor parte de las actualizaciones mecánicas. La próxima versión a largo plazo, QGIS 4.2, está prevista para octubre de 2026. Este es el plazo práctico, la versión que la mayoría de las organizaciones e instituciones adoptarán para su uso en producción.

¿Qué es lo que realmente necesita cambiar en tu plugin?

Si abres un complemento de Python que fue escrito para QGIS 3, normalmente verás líneas en la parte superior de cada archivo que se parecen a esto:

Ejemplo:


from PyQt5.QtCore import Qt, QTimer

from PyQt5.QtWidgets import QAction, QDialog

Estas líneas cargan las herramientas que tu complemento necesita desde Qt5. En Qt6, deben hacer referencia a Qt6 en su lugar, o mejor aún, usar una ruta independiente de la versión que proporciona QGIS:

Ejemplo:


from qgis.PyQt.QtCore import Qt, QTimer

from qgis.PyQt.QtWidgets import QDialog

El script de migración reescribe la mayoría de estas líneas automáticamente. Ejecútalo y escaneará tu directorio de plugins y actualizará las líneas de importación que reconozca.

Además, hay otros cambios:

Valores de opciones con nombre: Qt utiliza algo llamado “enums” (enumeraciones), que básicamente son valores con nombre que representan opciones. Piensa en ellos como configuraciones con nombre, en lugar de pasar el número 1 para indicar “alinear a la izquierda”, escribes Qt.AlignLeft. En Qt6, estos deben escribirse de manera más específica Qt.AlignmentFlag.AlignLeft. El script de migración detecta muchos de estos casos, pero no todos, especialmente cuando aparecen en código más complejo o condicional.

Componentes reubicados: Algunas herramientas de Qt cambiaron de ubicación entre versiones. Por ejemplo, QAction pasó de QtWidgets a QtGui. Estas son fáciles de corregir una vez que las conoces, pero solo se manifiestan como errores cuando realmente ejecutas esa parte del complemento.

Patrones antiguos de la API de QGIS: Actualmente, QGIS 4 mantiene compatibilidad con algunos patrones antiguos de la era de QGIS 2.x, pero no se garantiza que esto dure durante todo el ciclo de vida de la versión 4.x. Los complementos que dependen en particular de la antigua API de procesamiento deberían actualizarse.

Limitaciones del script de migración

El script es un buen punto de partida. Gestiona los cambios mecánicos y predecibles. Sin embargo, no puede verificar que el complemento funcione correctamente después de dichos cambios. La guía de migración del proyecto QGIS lo deja claro: pruebe su complemento exhaustivamente. Es un consejo fácil de dar. En la práctica, significa que se debe probar cada ruta de código en una sesión real de QGIS 4 en ejecución, y cuando algo falla, necesitas una forma de entender qué sucedió.

Segundo cambio: El nuevo escáner de seguridad

Independientemente de la migración a Qt6, el repositorio de complementos de QGIS introdujo un escaner de seguridad a principios de este año. Este sistema afecta a cualquier persona que publique un complemento, independientemente de si ya ha migrado a Qt6.

¿Por qué está sucediendo esto?

Los complementos de QGIS se ejecutan con Python y con los mismos permisos que el usuario que ejecuta QGIS en su computadora. Esto implica un amplio acceso. Hasta ahora, el repositorio se basaba principalmente en la confianza, una vez aprobado un complemento, podía republicarse libremente con relativamente poca supervisión. El nuevo sistema cambia esto de dos maneras.

En primer lugar, ahora la confianza recae en la persona, no en el complemento. Anteriormente, la confianza se otorgaba a un complemento y se mantenía independientemente de lo que se subiera posteriormente. Ahora, el repositorio realiza un seguimiento de los autores, si se descubre que un desarrollador actúa de mala fe, se puede sancionar a todo su portafolio de complementos de inmediato.

En segundo lugar, ahora todos los complementos pasan por un análisis de seguridad automatizado antes de poder ser publicados.

Lo que ve el escáner

El escaneo utiliza una herramienta llamada Bearer. Busca el tipo de problemas que son fáciles de introducir accidentalmente y difíciles de detectar a simple vista:

Credenciales ocultas en el código: Claves API, contraseñas o tokens de acceso codificados directamente en un complemento que no deberían estar ahí. Esto ocurre con más frecuencia de lo esperado, especialmente con complementos desarrollados rápidamente o con asistencia de IA.
Acceso excesivamente permisivo al sistema de archivos: Código que lee o escribe en ubicaciones del ordenador del usuario de forma que podría causar daños o exponer datos confidenciales.
Otros patrones conocidos de riesgo de seguridad: Prácticas que las herramientas de seguridad señalan como posibles vulnerabilidades.

También existe una capa de comprobaciones independiente y no intrusiva, una herramienta llamada flake8, que detecta problemas de estilo y calidad, como importaciones no utilizadas, formato inconsistente y otros aspectos similares. Estas comprobaciones no impiden la publicación, son solo recomendaciones.

Qué significan las insignias

Ahora, cada complemento del repositorio muestra una insignia. Una insignia roja indica que el escáner detectó problemas que requieren atención. Una insignia verde indica que el complemento superó todas las comprobaciones de bloqueo. Un pequeño icono con una “i” indica que hay avisos que no bloquean el funcionamiento y que conviene revisar.

Si eres el propietario de un complemento y este tiene una insignia roja, puedes iniciar sesión en plugins.qgis.org y ver el informe completo con todos los detalles de cada elemento marcado.

Lo que el escáner bloquea actualmente y lo que no

Para los complementos que se suben por primera vez, es necesario superar el análisis de seguridad. Los complementos ya publicados no se eliminan; conservan la insignia y se espera que los desarrolladores solucionen los problemas detectados en su próxima actualización.

Existen casos conocidos en los que un elemento marcado es intencional. Por ejemplo, un complemento que necesita incorporar una clave API para un servicio legítimo será marcado, sin embargo, los desarrolladores pueden marcar esas líneas específicas con una insignia de anulación en su código para indicar al escáner que el problema ha sido considerado y aceptado. El objetivo no es la aplicación automática, sino la revisión consciente, el proyecto QGIS busca que los desarrolladores hayan analizado cada problema marcado y tomado una decisión deliberada al respecto.

El equipo ha reconocido algunos problemas iniciales, algunas bibliotecas estándar de Python (el analizador XML, ciertas funciones de hash) estaban generando falsos positivos y el número de incidencias indicado en la insignia no siempre coincidía con la cantidad de elementos enumerados en el informe detallado. Estos problemas se están solucionando. Si crees que algo se está marcando incorrectamente, puedes informar del problema en github.com/qgis/QGIS-Plugins-Website.

Por ahora, las insignias solo son visibles en el sitio web de complementos. Todavía no aparecen dentro del propio administrador de complementos de QGIS Desktop, aunque eso está en la hoja de ruta.

Lo que ambos cambios tienen en común

La migración a Qt6 y el escáner de seguridad son de naturaleza diferente, pero comparten un requisito clave, en algún momento, tienes que ejecutar tu complemento y comprobar que realmente funcione.

El script de migración reescribe tus líneas de importación. Las herramientas de análisis estático (piensa en ellas como un corrector ortográfico para el código) pueden detectar patrones conocidos, pero ninguna de ellas dirá si una variable contiene el valor que esperas en un punto crítico, ni por qué la interfaz de QGIS se congela cuando un usuario activa una acción determinada. Lo mismo ocurre después de corregir fallos de seguridad, el código que supera el escáner aún debe funcionar correctamente en la práctica.

Durante la mayor parte de la historia del desarrollo de complementos para QGIS, la única herramienta disponible para esto era imprimir mensajes en la consola y cruzar los dedos, un proceso lento y frustrante, especialmente en complementos complejos. No había una forma limpia de adjuntar un depurador adecuado a una sesión de QGIS en ejecución.

Para cerrar esa brecha se creo QGIS DevTools.

QGIS DevTools, un depurador para una sesión en vivo de QGIS

QGIS DevTools es un complemento de QGIS gratuito, de código abierto bajo GPL-2.0 y disponible en el repositorio estándar de complementos de QGIS, que inicia un servidor de depuración dentro de la aplicación QGIS en ejecución y lo conecta a VS Code. Es compatible con Qt6, se actualizó a la versión 1.3.2 solo unos días antes del lanzamiento de QGIS 4.0.

Una vez que la conexión esté activa, podrás interactuar con tu complemento a través de QGIS con normalidad, pero ahora tendrás visibilidad total de lo que está ocurriendo dentro del código mientras se ejecuta.

Cómo se ve esto en la práctica

Breakpoints: Colocas un marcador en cualquier línea del código de tu complemento. Cuando la ejecución alcanza esa línea (desencadenada por cualquier acción que realices en QGIS), se detiene. La interfaz se congela (intencionalmente) y VS Code te muestra exactamente dónde te encuentras en el código.

Inspección de variables: En el momento de la pausa, cada variable que está en uso en ese momento es visible en el panel variables de VS Code. Para el trabajo de migración a Qt6, esto es especialmente valioso, puedes verificar que los valores con los que estás trabajando son los que Qt6 produce realmente, en lugar de lo que supusiste que te daría el script de migración. Para correcciones de seguridad, puedes confirmar que los valores sensibles se están manejando como pretendías.

La consola de depuración: Mientras está en pausa, puedes escribir expresiones y evaluarlas contra la sesión en vivo. Pregunta por las coordenadas del último clic del mouse, inspecciona un objeto de geometría, verifica el estado de cualquier variable, todo sin modificar tu código.

Ejecución paso a paso: En lugar de saltar al siguiente punto de interrupción, puedes avanzar línea por línea y observar exactamente cómo fluye la ejecución a través de una sección de código.

Múltiples instancias de QGIS: DevTools admite la ejecución de varias instancias de QGIS simultáneamente configurando un rango de números de puerto en lugar de uno solo. Esto es útil cuando deseas comparar el comportamiento entre una compilación de QGIS 3.x y una compilación de QGIS 4 una al lado de la otra.

El complemento también funciona con el editor de scripts de la consola Python de QGIS, hay un botón dedicado Debug Script que inicia la misma sesión de depuración para scripts independientes.

Configuración

Las instrucciones completas están en la documentación. La versión resumida:

Instala debugpy, la biblioteca de depuración subyacente, para tu sistema operativo:

Windows: agrégala a través del instalador de OSGeo4W en la categoría Libs
Linux: apt install python3-debugpy
macOS: /Applications/QGIS.app/Contents/MacOS/bin/python3 -m pip install debugpy

Instala QGIS DevTools desde el Repositorio de Complementos (Complementos → Administrar e instalar complementos → buscar “QGIS DevTools”)

Instala la extensión Python Debugger en VS Code (Extensiones → buscar “Python debugger”)

En QGIS, abre la carpeta de tu complemento en VS Code y luego presiona Start en el panel de DevTools

Copia la plantilla launch.json que aparece y pégala dentro de una carpeta .vscode dentro del directorio de tu complemento

En VS Code, ve a Run & Debug (Ctrl+Shift+D) y ejecuta “Attach to QGIS”

Cuando la sesión esté activa, el ícono de DevTools en la barra de estado de QGIS se vuelve verde y muestra “client connected”.

Un flujo de trabajo práctico para la migración a QGIS 4

Combinando tanto la migración a Qt6 como el escáner de seguridad, esta es una secuencia práctica:

Ejecuta pyqt5_to_pyqt6.py en el directorio de tu complemento.
Corrige los errores de importación y los problemas de valores con nombre que señale.
Atiende cualquier elemento bloqueante del informe del escáner de seguridad (inicia sesión en plugins.qgis.org para ver el tuyo).
Carga el complemento actualizado en QGIS 4.
Enlaza DevTools.
Establece breakpoints en las rutas de código que modificaste, particularmente en cualquier lugar donde el script de migración haya reescrito algo, y en cualquier lugar donde hayas modificado el código para abordar una alerta de seguridad.
Activa esas acciones en QGIS mediante el uso normal.
Inspecciona el contenido de las variables en cada punto de pausa y confirma que el comportamiento coincide con lo que esperas.
Recorre paso a paso cualquier sección donde algo parezca estar mal.

Los pasos 6 a 9 son lo que las herramientas automatizadas no pueden hacer por ti, y es donde la inversión de tiempo en una configuración de depuración adecuada da sus frutos.

Resumen rápido

QGIS 4.0 “Norrköping” se lanzó el 6 de marzo de 2026. Los complementos creados para Qt5 no funcionarán sin actualizaciones.
El proyecto QGIS proporciona un script de migración (pyqt5_to_pyqt6.py) y una guía de migración. El script gestiona los cambios previsibles. Aun así, se requieren pruebas en tiempo de ejecución.
Un nuevo escaner de seguridad revisa todos los complementos antes de su publicación. Los problemas que impiden su correcto funcionamiento deben resolverse antes de poder subir una nueva versión. Los complementos ya publicados reciben una insignia y un plazo para actualizarse.
Ambos cambios requieren que pruebes tu complemento en una sesión real de QGIS para verificar los resultados, no solo que revises el código.
QGIS DevTools proporciona la conexión entre VS Code y una sesión en vivo de QGIS 4 (breakpoints, inspección de variables y ejecución paso a paso).
El ciclo de vida de QGIS 3 LTR se ha ampliado para dar más tiempo a los desarrolladores de complementos. Se espera que QGIS 4.2 LTR esté disponible en octubre de 2026, fecha en la que la mayoría de los entornos de producción migrarán a esta versión, y que coincide con el plazo límite para la actualización a Qt6 y el cumplimiento de las normas de seguridad.

Preguntas frecuentes

¿Es compatible QGIS DevTools con QGIS 4.0? Sí. El complemento es compatible con Qt6 y se actualizó justo antes del lanzamiento de QGIS 4.0.

¿Es compatible con QGIS 3.x? Sí. Puedes empezar a usar DevTools hoy mismo en QGIS 3.x para familiarizarte con el flujo de trabajo antes de necesitarlo para las pruebas de migración.

No escribí mi propio plugin; usé un asistente de IA o adapté el código de otra persona. ¿Aun así me aplica esto? Sí, y podría decirse que es aún más importante. Las herramientas automatizadas son buenas para realizar cambios que parecen sintácticamente correctos. La única forma de saber si el resultado funciona correctamente es probarlo en una sesión real. Las herramientas para desarrolladores hacen que esas pruebas sean prácticas.

¿El uso de DevTools modifica de alguna manera el código de mi complemento? No. DevTools se conecta externamente a la aplicación QGIS en ejecución. Su complemento permanece intacto.

¿Qué entornos de desarrollo integrados (IDE) son compatibles? VS Code y Visual Studio, a través de debugpy. Está previsto ofrecer compatibilidad con otros entornos, como PyCharm y Eclipse.

Mi plugin tiene una insignia de seguridad roja. ¿Qué debo hacer? Inicia sesión en plugins.qgis.org y abre el informe detallado del plugin. Revisa los elementos marcados uno por uno. Para los elementos que son características genuinamente intencionales (por ejemplo, una clave API integrada que debe estar ahí), puedes agregar un marcador de anulación en su código. La guía del equipo de QGIS indica: revisa cada problema marcado, decide si lo corriges o lo aceptas, y documenta esa decisión en el código. La documentación completa sobre las reglas de escaneo está en plugins.qgis.org/docs/security-scanning .

¿DevTools es gratuito? Sí, es Open-source bajo la licencia GPL-2.0 y se puede instalar gratuitamente desde el repositorio de plugins. Si es necesario NextGIS también ofrece soporte comercial y desarrollo a medida.