Join our Newsletter — 33% off our NHI Course
Home› Guides› Package Cooldown and Minimum Release Age Guide: Per-Tool…
Guide Software & AI Supply Chain

Package Cooldown and Minimum Release Age Guide: Per-Tool Settings With a Security Fast Path

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 15 November 2026 17 min read
On this page

A cooldown only protects you if every tool that can resolve a new version enforces it, and most teams configure one bot and leave the package manager, the CI install and the lockfile refresh wide open. The 2025 and 2026 worm wave on npm and PyPI showed that malicious releases spread in minutes and are usually removed within hours, so a release-age delay of a few days is now one of the cheapest supply chain controls available. This guide is the configuration reference: the exact setting names, units and defaults for pnpm, npm, Yarn, Bun, uv, pip and Poetry, how Dependabot and Renovate apply their own delays, how to keep the bot and the installer in step, and how to build a security fast path so advisory fixes are not held back. It is for platform engineers, build owners and application security teams. Why to pin, and where each decision should live, is covered in the Dependency Pinning vs Version Ranges guide; bot grouping and auto-merge policy are in the Dependency Update Automation Guide. Settings below were checked against each project's documentation in November 2026.

Key takeaways

  • Set the delay in two places. Renovate's own documentation recommends configuring minimum release age in both the bot and the package manager, because a lockfile update can pull in transitive versions the bot never checked.
  • Units differ by tool, and mistakes are silent. pnpm counts minutes, npm counts days, Bun counts seconds, Yarn takes a duration string such as 3d, and uv accepts "7 days" or P7D. A value of 3 in Bun is three seconds.
  • Some defaults have changed. pnpm documents a built-in minimumReleaseAge of 1440 minutes (one day), Dependabot applies a 3-day cooldown to version updates even when none is configured, and Yarn 4.15.0 and later default npmMinimalAgeGate to one day.
  • Security fixes need their own lane. Dependabot cooldowns never apply to security updates, and Renovate waits only for the minimumReleaseAge of vulnerabilityAlerts, which is null by default. Installer-level gates do not know about advisories, so plan an exclusion path.
  • Measure enforcement, not configuration. Track installs that resolved a version younger than policy, bypass entries without an expiry, and the time from advisory to merged fix.

What a cooldown does and does not stop

A cooldown (Renovate calls it minimum release age, Dependabot calls it cooldown, pnpm and Bun call it minimumReleaseAge, npm calls it min-release-age) refuses to select any version published more recently than a set age. It targets the most common modern attack pattern: an attacker takes over a maintainer account or publishing token, publishes a poisoned patch release, and every consumer whose range admits that release picks it up on the next resolve.

The data favours short delays. In his November 2025 analysis of ten well-known supply chain attacks, William Woodruff found that eight had a window of opportunity of less than a week, with Nx at about four hours, rspack and the second Ultralytics phase at about one hour, and chalk under twelve hours. The exceptions were xz-utils (about five weeks) and the Kong Ingress Controller (about ten days). The axios npm compromise in March 2026 fits the pattern: the malicious 1.14.1 and 0.30.4 releases were live for roughly three hours, yet update bots proposed them within minutes and some bot pull requests were merged without review.

ThreatDoes a cooldown help?Control that covers the gap
Hijacked maintainer account publishes a new malicious versionYes, if the version is detected and removed before the delay expiresCooldown plus strict lockfile install
Self-propagating worm republishing many packages with stolen tokensYes for consumers; the speed of spread makes the delay more valuableCooldown, disabled install scripts in CI, token hygiene
Long-running maintainer compromise (xz-utils style)No: the malicious code outlives any practical delayCode review of dependency diffs, provenance checks, behavioural scanning
Typosquat or dependency confusion (a new package name)Partly: a brand-new package has only young versions, so a strict gate blocks itAllow lists, scoped registries, see the Malicious Package and Dependency Confusion Guide
Tampered artefact at an already-locked versionNoHash verification in the lockfile
Known vulnerability in your current versionCooldown can slow the fixSecurity fast path (below)

A cooldown also stops a resolver from adopting a version during the window in which the registry may still remove it. Renovate notes that npm packages less than 72 hours old can be unpublished, which is why its documentation suggests 3 days for npm as a minimum.

Installer-level settings: the reference table

The installer is the layer most teams forget. It governs every developer laptop, every CI job that resolves fresh, and every lockfile refresh a bot delegates to the package manager. The table lists the setting, where it lives, its unit and the documented default.

ToolSetting and locationUnit and formatDocumented defaultExclusion setting
pnpm (v10.16.0 and later)minimumReleaseAge in pnpm-workspace.yaml or global config.yamlMinutes (number)1440 (one day) in pnpm v11, non-strict unless set explicitlyminimumReleaseAgeExclude (names, patterns such as @myorg/*, exact versions from v10.19.0)
npm (v11.10.0 and later)min-release-age in .npmrc or --min-release-age; older alternative: before (an absolute date)Days (number)null (off)None documented; npm rejects min-release-age and before together
Yarn (v4.10.0 and later)npmMinimalAgeGate in .yarnrc.yml, also per scope under npmScopesDuration string, for example 1w or 10dOne day from v4.15.0npmPreapprovedPackages (descriptors or name globs)
Buninstall.minimumReleaseAge in bunfig.tomlSeconds (259200 = 3 days)null (off)install.minimumReleaseAgeExcludes (names or name@version)
uvexclude-newer in pyproject.toml [tool.uv] or uv.toml, or --exclude-newerRFC 3339 timestamp, friendly duration (24 hours, 1 week, 30 days) or ISO 8601 (P7D)None (off)exclude-newer-package, with false to exempt a package
pip--uploaded-prior-to or PIP_UPLOADED_PRIOR_TOISO 8601 datetime or P<n>D in whole daysOffNone documented
Poetry (v2.4.0 and later)solver.min-release-age, environment POETRY_SOLVER_MIN_RELEASE_AGEDaysNot setsolver.min-release-age-exclude

pnpm

  • Scope: the pnpm documentation states minimumReleaseAge applies to all dependencies, including transitive ones, which is what makes an installer gate stronger than a bot gate.
  • Strictness: minimumReleaseAgeStrict defaults to true when you configure the age explicitly and false otherwise. When false, pnpm falls back to a version that fails the age check so the install still succeeds. Set the age explicitly so resolution fails instead.
  • Missing timestamps: minimumReleaseAgeIgnoreMissingTime defaults to true, which skips the check for packages whose registry metadata has no time field. Set it to false where your registry or proxy supplies timestamps, so an absent timestamp is treated as unsafe.
  • Trust downgrade: trustPolicy: no-downgrade (default off) fails the install when a package's trust level is lower than in earlier releases, for example a package that moved from trusted publishing to a plain token. See the npm Trusted Publishing and Provenance Guide.
  • Error codes to alert on: ERR_PNPM_NO_MATURE_MATCHING_VERSION and ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION, which Renovate's documentation lists as the failures pnpm raises when its own gate refuses a version.

A minimal workspace file sets minimumReleaseAge: 4320 (three days), minimumReleaseAgeStrict: true, minimumReleaseAgeIgnoreMissingTime: false, minimumReleaseAgeExclude listing your internal scope, and trustPolicy: no-downgrade.

npm

  • Relative age: min-release-age=3 in the project .npmrc tells npm to build the tree only from versions available more than three days ago. Commit the .npmrc so CI and laptops share it.
  • Absolute date: before=<date> is the older option and is what Renovate passes as --before when it regenerates an npm lockfile. Do not set both: Renovate's documentation notes npm rejects the combination.
  • Version floor: min-release-age arrived in npm v11.10.0. Pin the npm version through the packageManager or devEngines field so older clients do not ignore the setting.
  • Existing locks: if a lockfile already contains versions younger than the cutoff, npm fails with ETARGET. Regenerate the lockfile once under the new policy rather than turning the gate off.

Pair the gate with install-script controls, because most malicious npm releases execute at install time. See the npm Install-Time Security Guide.

Yarn and Bun

  • Yarn: npmMinimalAgeGate is the minimum age of a version, by registry publish date, to be considered for installation. From Yarn 4.17.0 the one-day default also applies to each scope under npmScopes that sets no value of its own; a scope that sets npmMinimalAgeGate: 0 opts out, so review scope blocks for internal registries carefully. npmPreapprovedPackages excludes descriptors or globs from all package gates.
  • Bun: install.minimumReleaseAge is in seconds. Bun filters out versions published more recently than the threshold. minimumReleaseAgeExcludes takes names (every version) or name@version (only the listed versions), which is the safer form for a one-off security exception.

uv, pip and Poetry

  • uv: exclude-newer limits candidates to distributions uploaded before the cutoff, and the comparison uses the upload time of each individual distribution artefact, not the release date. Durations are fixed seconds (a day is 24 hours; months and years are not allowed). Use exclude-newer = "7 days" for a rolling cooldown, exclude-newer-package for a per-package override, and false to exempt your own packages.
  • pip: --uploaded-prior-to P3D considers only packages uploaded at least three days ago. The pip documentation warns it is only effective with indexes that provide upload-time metadata, so test it against your mirror before relying on it.
  • Poetry: solver.min-release-age and solver.min-release-age-exclude arrived in v2.4.0; older versions ignore them, so pin the Poetry version in CI.

Python packages carry the same publishing-token risk as npm. See the PyPI API Tokens and Trusted Publishing Security Guide.

Bot-level settings: Dependabot and Renovate

Bots decide when an update pull request is raised. They are the visible half of the control and the half most guidance covers, so this section concentrates on the details that cause gaps.

BehaviourDependabotRenovate
Settingcooldown block in dependabot.yml: default-days, semver-major-days, semver-minor-days, semver-patch-days, include, excludeminimumReleaseAge (formerly stabilityDays), with minimumReleaseAgeBehaviour and internalChecksFilter
Default3 days for version updates, even with no cooldown blockNot set; security:minimumReleaseAge* presets set it per ecosystem
Security updatesCooldown never appliesUses the minimumReleaseAge of vulnerabilityAlerts, null by default
Listsinclude and exclude, up to 150 entries each, * wildcards; exclude wins over includepackageRules with matchPackageNames, matchUpdateTypes, matchDatasources
Timestamp sourceRegistry release dataRequires a registry-provided timestamp; timestamp-required treats a missing one as not yet stable (the default from Renovate 42)
Passing age to the installerNot described in the options referencePasses --before to npm, and with minimumReleaseAgePackageManagerSync passes age values to pnpm, Yarn, Poetry and Cargo

Renovate details that matter

  • internalChecksFilter: strict (the default) creates no branch until the renovate/stability-days check passes, and shows held updates on the Dependency Dashboard. Avoid flexible, which Renovate warns can make pull requests flap between versions.
  • minimumReleaseAgeBuffer adds a margin (30 minutes by default) on top of the age Renovate waits, so companion packages published minutes after a main package have also cleared the installer's gate. Without it, the installer refuses to update the lock and the bot reports an artefact error.
  • minimumReleaseAgePackageManagerSync is an experimental flag that makes Renovate read the installer's own age and use the larger value. It passes the repository-level age, not a larger packageRules value, because the installer applies one age to the whole lockfile.
  • Update types not covered: Renovate's documentation lists pin, lockFileMaintenance, lockfileUpdate, rollback, bump and replacement updates as not enforcing minimumReleaseAge. Lockfile maintenance can only be gated by the installer, which is the strongest argument for the two-layer set-up.
  • Do not use it as a rate limit: the documentation says to use a schedule, not minimumReleaseAge, to slow fast-releasing projects. Each version is aged separately.

Choosing the delay

There is no single right number. Pick per update class and adjust for how much you trust the publisher.

Update classSuggested delayReasoning
Security fix for a published advisoryNone (fast path)The known risk outweighs the unknown one; review the diff instead
Patch releases of third-party packages3 daysCovers most observed malicious windows and npm's 72-hour unpublish window
Minor releases7 daysMore code changes; little value in speed
Major releases14 days or moreMigration work dominates; Renovate's own example uses 14 days
Internal packages from your own registry scopeNoneYou control the publisher; exclude them by scope
CI actions and base images3 to 7 days, pinned by SHA or digestThey run with pipeline secrets; Dependabot cooldown covers GitHub Actions and Docker

Installer value: set the installer gate to the shortest bot delay (usually the patch value), because the installer applies one age to the whole tree. A longer installer age blocks lockfile updates for packages the bot already approved.

Small teams: accept the Dependabot default, add min-release-age=3 or the pnpm or uv equivalent, and exclude your own scope. Large organisations: publish a shared Renovate preset or Dependabot template, enforce the same age at a registry proxy so every build is covered regardless of repository config, and report deviations centrally. Registry-side options are compared in the Package Registry Security Comparison Guide.

The security advisory fast path

A cooldown that holds back a critical fix is a vulnerability policy. Build the exception into the design rather than relying on someone turning the gate off under pressure.

  1. Let the bot raise the fix immediately. Dependabot does so by default. In Renovate, leave vulnerabilityAlerts.minimumReleaseAge unset and keep vulnerability alerts enabled; they skip schedules and hourly limits.
  2. Unblock the installer narrowly. Add the exact fixed version, not the package name, to the exclusion list: pnpm minimumReleaseAgeExclude with a version (v10.19.0 and later), Bun name@version, uv exclude-newer-package for that package, Yarn npmPreapprovedPackages with a descriptor. For npm, which documents no per-package exclusion, run the single fix through a reviewed lockfile update with the gate lowered in that pull request only.
  3. Review the fixed release itself. A brand-new fix version is also a brand-new version. Check the diff, the publisher and provenance before merge.
  4. Record and expire the exception. Every bypass entry carries an advisory ID, an owner and a removal date, and a CI check fails when an entry outlives its date.
  5. Remove the bypass after the delay. Once the fixed version is older than policy, the exclusion adds nothing and should be deleted.

During an active incident, the reverse applies: lengthen the gate temporarily, freeze lockfile refreshes and follow the Open source package compromise consumer response guide.

Rollout plan

  1. Inventory resolvers: list every package manager, version and install command in use per repository, including CI images and developer tooling. A gate only works on tool versions that understand it.
  2. Pin tool versions: set packageManager or devEngines for npm, pnpm and Yarn, and pin uv, Poetry and pip in CI images, so the setting is not silently ignored.
  3. Pilot ring: enable the installer gate and bot delay on a few well-tested repositories. Watch for ETARGET and pnpm age errors, regenerate locks once, and confirm the security fast path works end to end with a test advisory.
  4. Turn on strictness: pnpm strict mode and missing-time failures, Renovate timestamp-required and internalChecksFilter: strict.
  5. Roll out by preset: push the shared configuration to all repositories, then enforce at the registry proxy.
  6. Rollback: the change is configuration only. Revert the .npmrc, workspace or bot file; lockfiles generated under the gate stay valid because they only contain older versions.

Detection and measurement

  • Configuration drift: scan repositories for missing or zero values (min-release-age, minimumReleaseAge, npmMinimalAgeGate: 0 scopes, exclude-newer = false) and for Renovate minimumReleaseAge: null outside internal scopes.
  • Young versions in locks: compare each locked version's registry publish time with the merge time of the pull request that introduced it.
  • Gate errors: collect pnpm age violations and npm ETARGET failures from CI logs; repeated failures signal a mismatch between bot and installer values.
  • Bypass hygiene: count exclusion entries without an advisory reference or expiry date.
MetricTarget
Repositories with both installer and bot age configuredAll repositories resolving third-party packages
Merged updates to versions younger than policy (excluding fast path)Zero
Median time from advisory to merged fixWithin the remediation SLA, unaffected by the cooldown
Bypass entries older than their expiryZero
Builds on tool versions that ignore the settingFalling to zero

Common failure patterns

  • Bot-only cooldown: Dependabot waits three days but a developer runs a fresh install, or a lockfile refresh resolves a new transitive version the bot never aged. In the ChainDrop npm worm, the first unrelated package was infected about three minutes after the poisoned keyv release, far faster than any human review.
  • Wrong unit: minimumReleaseAge: 3 in pnpm is three minutes and in Bun three seconds. Write values with a comment stating the intended days.
  • Auto-merge before the age: auto-merge rules that do not wait for the release-age check reproduce the axios pattern, where bot pull requests were merged without a human.
  • Silent fallback: pnpm's non-strict default and missing-timestamp skip let young versions through. Make both explicit.
  • Cooldown on security fixes: applying the same delay to advisory-driven updates slows the patches that matter most.
  • Old tool versions: npm before v11.10.0, Yarn before v4.10.0 and Poetry before v2.4.0 do not apply these settings, and older Yarn aborts on the unknown key.

Framework mapping

FrameworkReferenceHow cooldowns contribute
MITRE ATT&CK v20T1195.001 Compromise Software Dependencies and Development Tools; T1195.002 Compromise Software Supply ChainReduces exposure to newly published malicious versions
NIST SP 800-53 Rev 5SR-3 Supply Chain Controls and Processes; SR-11 Component Authenticity; CM-3 Configuration Change Control; SI-2 Flaw RemediationControlled acceptance of components, with a defined path for flaw fixes
NIST CSF 2.0PR.PS-02 Software is maintained, replaced, and removed commensurate with riskRisk-based timing of updates
OWASP ASVS 5.0V15.2.1 components within documented update and remediation time framesThe fast path keeps cooldowns from breaching remediation time frames
CIS Controls v8.116.5 Use Up-to-Date and Trusted Third-Party Software ComponentsBalances currency against trust in new releases
ISO/IEC 27001:2022 Annex AA.5.21 Managing information security in the ICT supply chain; A.8.32 Change managementDocumented acceptance rules for third-party code

Where identity fits

Cooldowns buy time for the ecosystem to notice a stolen publishing credential. They do not replace protecting your own: if you publish packages, move to trusted publishing and short-lived tokens so your releases are not the next worm vector. See the npm Tokens Security Guide and the Shai-Hulud npm Worm Guide. Treat the update bot itself as a privileged non-human identity with scoped credentials.

Practitioner checklist

  • Configure an installer-level age for every package manager in use, in the committed project config.
  • Configure the bot delay per update class and keep the installer value at or below the shortest bot value.
  • Pin package manager versions so the settings are honoured everywhere.
  • Turn on strict modes: pnpm strict and missing-time failure, Renovate timestamp-required and internalChecksFilter: strict.
  • Exclude internal scopes by name, never by broad wildcard.
  • Document and test the security fast path, with exact-version exclusions that expire.
  • Block auto-merge until the release-age check passes.
  • Enforce the same age at the registry proxy for builds outside repository control.
  • Report young-version merges, gate errors and stale bypasses monthly.

Standards and references

Related NHI Mgmt Group resources: Dependency Pinning vs Version Ranges · Dependency Update Automation Guide · Open source package compromise · npm Install-Time Security Guide

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 15 November 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.