Qué está pasando con `uv.lock`
El caso descrito parte de una transición a Python 3.15 y de un comportamiento concreto de `uv`: al ejecutar comandos como `uv run pytest`, la herramienta puede dejar archivos `uv.lock` en el proyecto, normalmente marcados para no subirse al repositorio. En esa situación, el archivo de bloqueo conserva versiones concretas de dependencias y puede arrastrar una combinación que todavía no encaja bien con el intérprete que se está usando.
El ejemplo citado es revelador. El error menciona `watchfiles==1.1.1`, un fallo al construir la rueda con `maturin.build_wheel` y una incompatibilidad entre el intérprete configurado, Python 3.15, y el máximo soportado por PyO3, que en ese caso era Python 3.14. La conclusión práctica es simple: el bloqueo estaba forzando una versión que no podía compilarse en ese entorno.
Por qué borrar el archivo puede arreglarlo
La lógica detrás del consejo es que `uv.lock` no siempre es el archivo adecuado para un proyecto, especialmente cuando se trata de librerías. En el material disponible, `uv` sí genera ese archivo al crear un entorno de trabajo, pero también se ve que no siempre hace falta pensar en él para ejecutar pruebas o instalar dependencias de desarrollo. Cuando un `uv.lock` aparece por accidente o queda en el directorio de trabajo tras ejecutar tests, puede acabar imponiendo una resolución de dependencias que ya no es válida.
Borrar ese archivo obliga a `uv` a resolver de nuevo el conjunto de dependencias. Si el problema era una versión atascada en el bloqueo anterior, la nueva resolución puede elegir una combinación distinta que sí tenga soporte para Python 3.15. En términos prácticos: no arregla el paquete problemático, pero sí permite que el gestor vuelva a buscar una solución compatible.
Qué conviene entender si usas Python 3.15
El detalle importante no es solo que haya un error, sino por qué aparece con más facilidad justo al cambiar de versión de Python. Cuando se adopta una versión nueva del intérprete, parte del ecosistema tarda un tiempo en publicar ruedas preparadas para ella. Mientras eso ocurre, un archivo de bloqueo antiguo puede seguir apuntando a una versión que aún no está lista. En ese escenario, el síntoma no es necesariamente un fallo del código propio, sino una combinación de dependencia, compilación y compatibilidad de versiones.
Eso afecta sobre todo a flujos de trabajo en los que se alterna con frecuencia entre proyectos, pruebas locales y entornos reproducibles. Si una instalación previa dejó un `uv.lock` y luego se cambió a Python 3.15, la huella de esa resolución anterior puede quedarse como una inercia técnica. El consejo de borrarlo funciona precisamente porque elimina esa memoria de resolución y deja que el gestor rehaga el encaje.
Lo que sí y lo que no confirma este caso
Lo que queda confirmado es limitado pero útil: en el caso descrito, eliminar `uv.lock` y volver a ejecutar `uv run pytest` suele resolver el problema. También queda claro que el bloqueo puede apuntar a dependencias que todavía no tienen soporte listo para Python 3.15.
Lo que no se puede generalizar es que esa sea la solución universal para cualquier error de `uv` o cualquier incidencia de compilación en Python. Aquí no se documenta una causa única para todos los casos, solo un patrón de trabajo muy concreto con una compatibilidad rota entre versión de Python, dependencia bloqueada y soporte de ruedas. Si el fallo procede de otro origen, borrar el archivo no bastará.
Una regla de emergencia útil para desarrolladores
La utilidad de esta nota está en su sencillez: cuando un proyecto empiece a comportarse de forma extraña tras pasar a Python 3.15, revisar el `uv.lock` puede ser un primer paso razonable antes de perder tiempo buscando problemas más profundos. No es una solución elegante, pero sí una heurística práctica para volver a un estado limpio y dejar que el gestor de dependencias rehaga la selección.
La siguiente pregunta es cuánto tardarán las dependencias más comunes en publicar soporte completo y evitar que este tipo de bloqueo vuelva a aparecer en nuevos proyectos. Eso, y no solo el archivo en sí, será lo que determine si este consejo deja de ser un apaño y pasa a ser una rareza.
