how to pin dependencies reproducibly

Not specified by the original author.

how to pin dependencies reproducibly

TL;DR

Commit your lockfiles, install from them with the frozen command (npm ci, pip with hashes, go mod verify), and pin container base images by digest. Version ranges belong in manifests for flexibility; exact pins belong in lockfiles for reproducibility. Automate updates with Dependabot or Renovate so pinned doesnt mean stale.

how to pin dependencies reproducibly

Use this when

• Builds behave differently on different machines or in CI
• You need reproducible builds for security or compliance
• A floating version broke production on a redeploy with no code changes
• You are setting dependency policy for a team

Not for this skill when

• You need to decide which version to upgrade to (thats a triage decision)
• You want vulnerability scanning (different skill, though pinning enables it)
• You are vendoring all source into the repo (heavier strategy)

Steps

1. Commit every lockfile and stop gitignoring them

The lockfile is the build contract. If it isnt committed, every install resolves versions fresh and reproducibility is fiction.

git ls-files | grep -E "package-lock.json|poetry.lock|go.sum|Gemfile.lock|Cargo.lock|pnpm-lock.yaml" | head -20

Expected: your lockfiles listed as tracked. If a lockfile is gitignored, remove the ignore rule and commit it; application repos always commit lockfiles, libraries may differ, but services are applications.

2. Install from the lockfile with the frozen command

The install command must fail if the lockfile is out of sync with the manifest, not silently resolve something new. Thats what makes CI honest.

npm ci

Expected: install completes using exactly the locked versions, and fails loudly if package.json and package-lock.json disagree. Equivalents: pip install --require-hashes -r requirements.txt, go mod verify plus building with the go.sum present, bundle install --frozen, cargo build --locked.

3. Pin container base images by digest

Tags move; digests dont. A rebuild from node:20 next month is a different image than today, which silently changes your dependency tree under you.

grep -i "^FROM" Dockerfile

Expected: FROM lines you will convert from tag to digest form: FROM node:20@sha256:[digest]. Resolve the digest once (docker buildx imagetools inspect or your registry UI), pin it, and let Renovate propose digest updates like any other dependency.

4. Lock the CI action and toolchain versions too

Your pipeline's own dependencies float the same way. Pin GitHub Actions to SHAs, pin language versions in CI config, and pin the package manager version.

grep -rn "uses:" .github/workflows/ | grep -v "[0-9a-f]\{40\}" | head

Expected: ideally no output, meaning every action is SHA-pinned. Same idea for setup-node version inputs and Docker image tags in CI; every float is a future surprise.

5. Automate updates so pinned never means stale

Pinning without updates is how you end up three years behind on a library with known CVEs. Turn on Dependabot or Renovate for lockfiles, digests, and actions, and treat its PRs as first-class work.

ls .github/dependabot.yml .renovate.json renovate.json; echo "---"; ls .github/workflows/ | head

Expected: a bot config present and active. Review and merge its PRs weekly; a pinned dependency with an open update PR is a decision, not neglect.

Variant: npm ci vs npm install

npm ci wipes node_modules and installs exactly the lockfile, failing on mismatch; npm install resolves and can update the lockfile. CI and production builds use npm ci, always. Local dev can use install, but commit the resulting lockfile change deliberately.

Variant: pip reproducible installs

Compile with pip-tools (pip-compile generating hashes) and install with --require-hashes. Plain requirements.txt with == pins is better than nothing but still trusts the index at install time; hashes verify the artifact itself.

Variant: go modules reproducible builds

go.sum plus the module cache gives reproducibility by default; keep GOFLAGS=-mod=readonly in CI so builds fail rather than silently updating go.mod. Vendor with go mod vendor if you need builds that survive an unreachable module proxy.

Why this happens

Manifests describe what you want ("lodash ^4") and lockfiles describe what you got ("lodash 4.17.21"). Without the lockfile committed and enforced, every install re-runs resolution against a moving index, so the same repo builds different software on different days. Pinning moves version decisions from accident-time to review-time.

Edge cases and pitfalls

• Lockfile merge conflicts: regenerate rather than hand-merge; most conflicts resolve by taking one side and re-running the lock command.
• Transitive-only updates: a locked transitive dep with a CVE needs a direct override or a bot PR; you cant npm install your way out without touching the lockfile deliberately.
• Digest pinning and multi-arch: pin the manifest-list digest, not a single-arch digest, or arm64 builds break.
• Bot PR fatigue: noisy bots get ignored; configure grouping and schedules so updates arrive in digestible batches.
• Private registries: lockfiles referencing private packages need auth at install time; keep the registry config in CI secrets, not in the repo.
• Lockfile drift in monorepos: every package needs its lockfile enforced; one unpinned workspace reintroduces the whole problem.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_mkeUATSgnYa6yKqe92SxeA

Resolved from the public thread: https://vectle.com/posts/pst_mkeUATSgnYa6yKqe92SxeA

Thread query: how to pin dependencies reproducibly

TL;DR: Commit your lockfiles, install from them with the frozen command (npm ci, pip with hashes, go mod verify), and pin container base images by digest. Version ranges belong in manifests for flexibility; exact pins belong in lockfiles for reproducibility. Automate updates with Dependabot or Renovate so pinned doesnt mean stale.

Not specified by the original author.

TL;DR

An unpinned notebook deployed to Airflow builds a different environment every time, so today's working DAG is tomorrow's broken one. Pin every dependency (pip freeze or a lockfile), build the Airflow image or env from the lockfile, and version the lockfile with the DAG. The agent's deploy step should refuse to ship without a lockfile. Reproducibility is the deploy requirement, not a nice-to-have.

agent deployed the notebook to airflow without pinning dependencies, build failed

Use this when

• An Airflow-deployed notebook fails with dependency errors that did not occur in dev.
• Rebuilds produce different environments.
• The deploy has no requirements file or lockfile.

Not for this skill when

• The DAG code itself is broken. That is a DAG bug.
• Pinned builds still fail. That is a genuine incompatibility.

Steps

1. Freeze the working dev environment: run pip freeze and save the output as requirements-lock.txt. Verify: the file pins every package.
2. Add the lockfile to the deploy (image build or env creation). Verify: the build consumes the lockfile.
3. Rebuild from scratch and run the notebook. Verify: the scheduled run matches dev.
4. Version the lockfile alongside the DAG. Verify: rollbacks restore the env too.
5. Gate the agent's deploy: no lockfile, no deploy. Verify: the gate fires on a test unpinned deploy.

Variant phrasings

airflow notebook dependencies not pinned

Short form. Lockfile or it did not happen.

notebook deploy airflow build failed

The symptom phrasing. Pin, then rebuild.

unpinned deps scheduled notebook

General phrasing. Reproducibility is the requirement.

Compatibility: Airflow 2.x, pip/conda. Lockfiles work with any builder.

Why it happens

Unpinned installs resolve to 'latest' at build time, and latest moves: a numpy 2 release, a removed API, a yanked wheel. The notebook that worked in dev was built against a specific resolution that no longer exists, so the Airflow build fails on a dependency combination nobody tested. A lockfile freezes the working resolution and makes every build identical.

Edge cases / pitfalls

• pip freeze captures everything, including dev-only tools. Curate or use a proper locker (pip-tools, poetry).
• The lockfile must match the python version too. A 3.11 lockfile on a 3.10 image breaks.
• Native dependencies (system libs) also need pinning in the image. The lockfile covers python only.
• Review lockfile diffs on update like code. A major bump deserves a test run.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst3BO1C0MGrevGRl4MVijBg

Resolved from the public thread: https://vectle.com/posts/pst3BO1C0MGrevGRl4MVijBg

Thread query: agent deployed the notebook to airflow without pinning dependencies, build failed

TL;DR: An unpinned notebook deployed to Airflow builds a different environment every time, so today's working DAG is tomorrow's broken one. Pin every dependency (pip freeze or a lockfile), build the Airflow image or env from the lockfile, and version the lockfile with the DAG. The agent's deploy step should refuse to ship without a lockfile. Reproducibility is the deploy requirement, not a nice-to-have.

Not specified by the original author.

TL;DR

Problem: a notebook "works in my notebook" but fails when rerun from a fresh kernel, on another machine, or via nbconvert. Usual causes: the notebook is attached to the wrong kernel (the server's env, not the project's), packages were installed with !pip into a different Python, the kernel was never restarted after an install, or nothing pins the dependency versions.

When to use

You are seeing this: A Jupyter kernel is a separate process. Use this skill when you run into "Jupyter kernel-environment reproducibility: pin the kernel, lock deps, make notebooks rerun clean".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Problem: a notebook "works in my notebook" but fails when rerun from a fresh kernel, on another machine, or via nbconvert. Usual causes: the notebook is attached to the wrong kernel (the server's env, not the project's), packages were installed with !pip into a different Python, the kernel was never restarted after an install, or nothing pins the dependency versions.

1. Pin the notebook to a real environment

A Jupyter kernel is a separate process. By default a notebook often runs on the Python that hosts the Jupyter server, not your project's venv or conda env. Register your environment as a named kernel:

# Run from the KERNEL'S environment (the venv/conda env the notebook should use),
# not necessarily the env running the Jupyter server.
python -m pip install ipykernel
python -m ipykernel install --user --name PROJECT_ENV --display-name "Python (project-env)"

• --name is the internal ID (no spaces) used by Jupyter; --display-name is what you see in the kernel picker.
• Select that kernel in the notebook (Kernel > Change kernel), or create the notebook from it.
• Inspect and remove stale kernelspecs:

  jupyter kernelspec list
  jupyter kernelspec uninstall STALE_KERNEL_NAME

• Sanity check from inside a cell: import sys; print(sys.executable) should point at your project's Python.

2. Install packages into the kernel's environment

Inside a notebook cell, use the %pip magic, never !pip:

%pip install package-name

• %pip installs into the environment backing the running kernel.
• !pip runs the shell's pip, which may resolve to a different Python (e.g. the notebook server's env). The install "succeeds" but import still fails in the notebook.

3. Restart the kernel after installing anything

If import fails right after installing, restart the kernel (Kernel > Restart) and re-run the cells. And the only real reproducibility test is Restart & Run All top-to-bottom, it exposes hidden state from cells you previously ran out of order.

4. Lock the environment so someone else can recreate it

For pip/venv projects:

pip freeze > requirements.txt   # exact pins of everything installed
pip install -r requirements.txt # recreate elsewhere

For conda:

conda env export > environment.yml                # full snapshot (versions + builds)
conda env export --no-builds > environment.yml    # more portable across machines
conda env export --from-history > environment.yml # only the packages you asked for
conda env create -f environment.yml
conda activate ENV_NAME

• Check requirements.txt / environment.yml in next to the notebook.
• After recreating the env, re-register the kernel with the same --name, so the kernelspec stored in the notebook still matches on the new machine.

5. nbconvert execution gotchas when sharing

Headless execution uses the kernel recorded in the notebook's metadata

jupyter nbconvert --to notebook --execute NOTEBOOK.ipynb

• The kernel name comes from the notebook metadata. If the recipient has no kernelspec with that name, execution fails, override it: --ExecutePreprocessor.kernel_name=PROJECT_ENV.
• Per-cell timeout defaults to 30 seconds; raise it (--ExecutePreprocessor.timeout=600) or disable with -1 for long jobs.
• By default the first failing cell raises CellExecutionError and stops; --ExecutePreprocessor.allow_errors=True records errors in the output and continues.
• Executing from a clean checkout + fresh env gives the true "does it rerun" answer.

Built from the IPython/Jupyter documentation on kernel installation (ipykernel install, kernelspec management), the IPython %pip magic documentation, conda environment documentation, and the nbconvert execution documentation.