guides

Un lockfile est un fichier que votre gestionnaire de paquets ecrit pour enregistrer les versions exactes de chaque dependance installee par votre projet, non seulement celles que vous avez demandees, mais aussi les dependances de ces dependances. Sa raison d'etre est la reproductibilite : il garantit que vous, votre collegue et votre serveur de production installez tous, octet pour octet, le meme ensemble de paquets, au lieu de ce qui se trouve etre le plus recent au moment de l'installation. Si vous avez deja vu un package-lock.json, yarn.lock ou Cargo.lock en vous demandant a quoi il sert, c'est cela.

Pour comprendre pourquoi c'est important, il faut regarder ce que dit reellement votre manifeste. Un fichier comme package.json epingle en general les dependances sous forme de plages de versions, et non de versions exactes, par exemple ^1.2.3, ce qui, selon le SemVer, signifie n'importe quelle version depuis 1.2.3 jusqu'a 2.0.0 exclue. Cette souplesse est utile, mais elle a un inconvenient : installez le projet aujourd'hui et vous pourriez obtenir 1.2.4, installez-le le mois prochain et vous pourriez obtenir 1.2.9. Meme manifeste, code reel different.

Le lockfile comble cet ecart. Lors de la premiere installation, le gestionnaire de paquets resout toutes ces plages en versions concretes, et les inscrit dans le lockfile avec un hash d'integrite pour chaque paquet. Des lors, quiconque installe lit le lockfile et obtient ces versions exactes, non pas la plage, mais la version resolue precise. Le resultat est une installation deterministe et reproductible a chaque fois, ce qui elimine toute une categorie de bugs du type 'mais ca marche sur ma machine'.

Ce hash d'integrite remplit une seconde fonction importante. Chaque entree du lockfile enregistre une somme de controle du contenu du paquet, si bien que lorsque le gestionnaire de paquets telecharge une dependance il peut verifier que les octets correspondent a ce qui a ete verrouille. Si un paquet du registre avait ete altere, le hash ne correspondrait pas et l'installation echouerait. A l'ere des attaques sur la chaine d'approvisionnement, cette verification represente un benefice de securite discret mais reel.

Chaque ecosysteme a sa propre version de la meme idee. En JavaScript, il y a package-lock.json (npm), yarn.lock (Yarn) et pnpm-lock.yaml (pnpm) ; en Rust, Cargo.lock ; en Python, poetry.lock et uv.lock ; en Ruby, Gemfile.lock ; en PHP, composer.lock. Le format du fichier differe, mais la fonction est identique : enregistrer l'arbre de dependances resolu exact afin qu'il puisse etre reproduit a l'identique.

Une question frequente est de savoir si vous devez committer le lockfile dans le controle de version. Pour les applications, oui : vous voulez que vos deploiements installent les versions exactes que vous avez testees, le lockfile a donc sa place dans le depot. Pour les bibliotheques, la convention est differente : de nombreux auteurs de bibliotheques ne committent pas de lockfile, car les projets qui dependent de la bibliotheque resoudront et verrouilleront de toute facon leurs propres versions.

Le lockfile et le manifeste forment une equipe, pas des rivaux. Le manifeste exprime une intention avec des plages SemVer, 'je veux une 1.x compatible de ce paquet', ce qui vous laisse ouvert aux mises a jour sures. Le lockfile enregistre la realite, 'cette version exacte est celle que nous utilisons vraiment', ce qui garde les installations reproductibles. Si vous voulez les details des plages elles-memes, consultez notre guide sur le SemVer.

La facon dont le lockfile se met a jour depend de la commande que vous executez. Une installation ordinaire (comme npm install) peut mettre a jour le lockfile si elle trouve des versions plus recentes encore autorisees par vos plages. Une installation stricte et reproductible (comme npm ci) ignore entierement les plages et installe exactement ce que dit le lockfile, en echouant si les deux different, ce qui est justement ce que vous voulez en CI et dans les builds de production.

Quelques habitudes pratiques rendent les lockfiles indolores. Ne les editez pas a la main ; laissez l'outil les regenerer. Lorsque vous obtenez un conflit de fusion dans un lockfile, ce qui arrive parce que deux branches ont ajoute des dependances, resolvez-le en relancant l'installation plutot qu'en editant le fichier a la main. Et committez toujours le lockfile pour une application, afin que la version que tout le monde build soit la version que vous avez reellement testee.