guides

Un lockfile es un archivo que tu gestor de paquetes escribe para registrar las versiones exactas de cada dependencia que instalo tu proyecto: no solo las que pediste, sino tambien las dependencias de esas dependencias. Todo su proposito es la reproducibilidad: se asegura de que tu, tu companero de equipo y tu servidor de produccion instalen todos el mismo conjunto de paquetes byte por byte, en lugar de lo que resulte ser mas reciente en el momento de la instalacion. Si alguna vez has visto un package-lock.json, yarn.lock o Cargo.lock y te has preguntado para que sirve, esto es exactamente eso.

Para ver por que importa, tienes que fijarte en lo que tu manifiesto dice realmente. Un archivo como package.json normalmente fija las dependencias como rangos de version, no como versiones exactas: por ejemplo ^1.2.3, que bajo el Versionado Semantico significa cualquier lanzamiento desde 1.2.3 hasta, pero sin incluir, 2.0.0. Esa flexibilidad es util, pero tiene una desventaja: instala el proyecto hoy y podrias obtener 1.2.4, instalalo el mes que viene y podrias obtener 1.2.9. El mismo manifiesto, un codigo real distinto.

El lockfile cierra esa brecha. Cuando instalas por primera vez, el gestor de paquetes resuelve todos esos rangos hasta versiones concretas y las escribe en el lockfile junto con un hash de integridad para cada paquete. A partir de entonces, cualquiera que instale lee el lockfile y obtiene esas versiones exactas: no el rango, sino la version resuelta especifica. El resultado es una instalacion determinista y reproducible cada vez, que es lo que elimina toda una clase de errores del tipo 'pero funciona en mi maquina'.

Ese hash de integridad cumple una segunda funcion importante. Cada entrada del lockfile registra una suma de verificacion del contenido del paquete, de modo que cuando el gestor de paquetes descarga una dependencia puede verificar que los bytes coinciden con lo que quedo bloqueado. Si un paquete del registro hubiera sido manipulado, el hash no coincidiria y la instalacion fallaria. En una era de ataques a la cadena de suministro, esa verificacion es un beneficio de seguridad discreto pero real.

Cada ecosistema tiene su propia version de la misma idea. En JavaScript esta package-lock.json (npm), yarn.lock (Yarn) y pnpm-lock.yaml (pnpm); en Rust, Cargo.lock; en Python, poetry.lock y uv.lock; en Ruby, Gemfile.lock; en PHP, composer.lock. El formato del archivo difiere, pero la funcion es identica: registrar el arbol de dependencias resuelto exacto para que pueda reproducirse exactamente.

Una pregunta habitual es si deberias incluir el lockfile en el control de versiones. Para aplicaciones, si: quieres que tus despliegues instalen las versiones exactas que probaste, asi que el lockfile pertenece al repositorio. Para bibliotecas la convencion es distinta: muchos autores de bibliotecas no incluyen un lockfile, porque los proyectos que dependen de la biblioteca resolveran y bloquearan sus propias versiones de todos modos.

El lockfile y el manifiesto forman un equipo, no son rivales. El manifiesto expresa la intencion con rangos SemVer ('quiero una 1.x compatible de este paquete'), lo que te mantiene abierto a actualizaciones seguras. El lockfile registra la realidad ('esta version exacta es la que usamos en verdad'), lo que mantiene las instalaciones reproducibles. Si quieres los detalles de los rangos en si, consulta nuestra guia sobre el Versionado Semantico.

Como se actualiza el lockfile depende del comando que ejecutes. Una instalacion normal (como npm install) puede actualizar el lockfile si encuentra versiones mas nuevas todavia permitidas por tus rangos. Una instalacion estricta y reproducible (como npm ci) ignora los rangos por completo e instala exactamente lo que dice el lockfile, fallando si ambos discrepan, que es lo que quieres en la integracion continua y en las compilaciones de produccion.

Unos pocos habitos practicos mantienen los lockfiles sin dolores de cabeza. No los edites a mano; deja que la herramienta los regenere. Cuando tengas un conflicto de fusion en un lockfile, que ocurre porque dos ramas anadieron dependencias, resuelvelo volviendo a ejecutar la instalacion en lugar de editar el archivo a mano. Y siempre incluye el lockfile en el control de versiones para una aplicacion, de modo que la version que todos compilan sea la version que realmente probaste.