Home / Knowledge hub / Package pinning
Knowledge hub
Package pinning
Fixing a dependency to one exact version rather than accepting any newer release.
What it means
Package pinning means telling your build to use one exact version of a dependency, such as 4.17.21, instead of a range such as 4.x or latest. A lockfile does this for the whole tree, including transitive dependencies.
Pinning can go further. Hash pinning records a cryptographic hash of the package file, so even the same version number with different contents is refused. Pip supports this with --require-hashes.
Why it matters
Without pins, the same build can give different results on different days. A new release of a library, good or bad, flows into your product the next time you build. If that release was published by a hijacked account, you ship it without a decision.
Pinning makes changes deliberate. Combined with review, it stops surprise updates and defends against some forms of dependency confusion and malicious packages.
How it shows up
Use the lockfile your package manager generates, commit it, and install from it in CI. In container builds, pin base images by digest. In CI workflows, pin third-party actions to a full commit hash rather than a movable tag.
The cost is staleness. Pinned versions do not receive fixes by themselves, so pair pinning with a routine of updates and a dependency update bot that proposes new versions as pull requests. Pinning without updating trades one risk for another.
Questions people ask
Package pinning, answered
Is a lockfile the same as pinning?
It does the same job for the full tree. It records exact versions, and often hashes, of everything that was resolved.
Does pinning make us safer?
It prevents surprise changes and makes builds repeatable. It does not remove flaws in the version you pinned.
What is the downside?
Pinned versions go out of date. You must update on a schedule and when fixes are published.
Should we pin GitHub Actions?
Yes, to a full commit hash for third-party actions. Tags can be moved, a commit hash cannot.
What is hash pinning?
It checks the contents of a downloaded package against a recorded hash, so a swapped file is rejected.
Sources
Where this comes from
Related
Terms that sit next to this one
Lockfile
A file pinning exact dependency versions so builds are repeatable and checkable.
Dependency update bot
A tool that opens pull requests when your libraries have newer or safer versions.
Transitive dependency
A library pulled in by another library you chose, which you still ship.
Reproducible builds
Builds that produce identical output every time, so tampering shows up.
Malicious package
A published library built to steal data or run code on whoever installs it.
Are your builds repeatable?
Pinning controls what goes in. We test what comes out: the running app, with each finding proven. Ask us to run it on one of your applications.
Or start with a $199 pilot on one application: thirty days, success criteria agreed before day one, credited against the annual if you convert.