---
title: "Align npm dist-tags with upstream registries"
description: "By default, Cloudsmith assigns the `latest` dist-tag to the package with the highest semantic version number, which may not match what the upstream registry considers `latest`.  A new per-repository setting, npm upstream tags take precedence, lets upstream distribution tags (dist-tags) override Cloudsmith’s semantic versioning (SemVer)-based tag assignment. "
canonical_url: "https://cloudsmith.com/changelog/align-npm-dist-tags-with-upstream-registries"
last_updated: "2026-06-09T14:15:09.116Z"
---
# Align npm dist-tags with upstream registries

By default, Cloudsmith assigns the `latest` dist-tag to the package with the highest semantic version number, which may not match what the upstream registry considers `latest`.

A new per-repository setting, **npm upstream tags take precedence**, lets upstream distribution tags (dist-tags) override Cloudsmith’s semantic versioning (SemVer)-based tag assignment.  
  
When enabled, Cloudsmith's npm metadata logic still uses SemVer as the baseline, then checks for the `latest` dist-tag in the upstream registry. The upstream tag is applied as an override only if the corresponding version is present within the versions available to the client. If the version is not available (which can be affected by index policy controls, like cooldown policies), the `latest` tag defaults to the semantically highest available version.

## Who this is for

npm users who want to closely replicate npm upstreams. For example, engineering teams who:

- Publish packages to both npmjs.com and Cloudsmith
- Use release tooling that depends on dist-tags
- Pull packages using tag-based resolution (e.g. @latest or @next) rather than pinned versions

## How it works

You can configure upstream tag precedence for a repository by setting `"npm_upstream_tags_take_precedence": true` via the API, or by enabling the **npm upstream tags take precedence** option in the repository settings form:

```json
{
  "_key": "c7fe82266af1",
  "_type": "image",
  "alt": "An image showing the 'User/Self privileges' repository settings view in the Cloudsmith web app.",
  "asset": {
    "_createdAt": "2026-06-09T13:47:34Z",
    "_id": "image-8310d84208e36f92aa5dfab9f059dd255a232934-755x923-png",
    "_rev": "oSfKj7JL3ujFPtCVAEqppj",
    "_type": "sanity.imageAsset",
    "_updatedAt": "2026-06-09T13:47:34Z",
    "assetId": "8310d84208e36f92aa5dfab9f059dd255a232934",
    "extension": "png",
    "metadata": {
      "_type": "sanity.imageMetadata",
      "blurHash": "e8S6Y[ICM}x^-p~qtRf4n$M|$*MyM}ozWAxsxsxtaxt8ofRlRkjYt6",
      "dimensions": {
        "_type": "sanity.imageDimensions",
        "aspectRatio": 0.8179848320693391,
        "height": 923,
        "width": 755
      },
      "hasAlpha": true,
      "isOpaque": true,
      "lqip": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAYCAYAAAD6S912AAAACXBIWXMAAAsTAAALEwEAmpwYAAACz0lEQVR4nKWVyY7USBCG+/1Pc+Ad5jziwAUJRiMhDogTMGgO02staadz3738KMKuorulVoO6pF+usp1f7FEXxnn0ykAMGt2gYX3EOM1YgN8WfS5SaXCpwsYMFzN8KihtQptmjPOC6Z4e/36seV5wkeoME0foUKFDhvaryEhqM+q0PFCb8KTGaQPqOGLwBYNPUD6zTChwuSGU8azVAJ5UW4ELBt8gXYYmSGrw+aQNRtf8i0CfZxxNQ2cozIbcZpRxYeXtel+/BNzrCqFX4HOHngU6AqqKg0qwqb4c6POMg6o46shACvlFwFhm9JZCjlzZVKeXAVOd0JuEfW8hlIOJKzS1aSvQ+vJapJnv31feivjQQ1Owlw4HadCbAOUilEvc3LlRdYFQJo6A7v9UhGUH5p9AOqBDg9CBgYfB8vU4WGiXEMsEynPvGo4q4CgtPztdlUvnNDGQvlATU7h3QuGuU9j1BHQYXIKNlUdTmMaFo/dInfKQJj5otQfAo3K4FQNDybq0FE7dxm6dd+UyBhtZNO90Lt/rinPIJhLQY99r7Hp9zqXfrCdKSxy5eJ327B1ByVihCeLF8WiWV6DZpDksSjgZdHnBwTTsh8B5I4P0nPJnY2FPT3POQMVFiZw3OnB6+RSS3caTgPSMi3LKpT5523i9cdtIV9GbCGk8pPbQLiLmilIppAm+TOgsGU2QJjCA24bXXYIJGbGOWx/GAkk5Ez1kJyCFgOp7eKORnEX2FsGRFxnSrX3IgDKy93lTHZetKM5C7XcQ11c4XF3ieHWJ/uYSancDc7iFFzskKRBchMsj70iGnZfIsum0bUzAl+8HvPt4jbcfrvHx8w1ur/ZwvUCQAmnoUK1CzYWryRV9YiMxsNMNbz4ZvHrd4Y+/BP58L/HfbUDOBbUU1FxRa0Mdn99Cq4dpxre7in/+zfj7a8Ln/wuEnc5LgcUePS/6V/wBZCtEk6IE8/8AAAAASUVORK5CYII=",
      "palette": {
        "_type": "sanity.imagePalette",
        "darkMuted": {
          "_type": "sanity.imagePaletteSwatch",
          "background": "#646b70",
          "foreground": "#fff",
          "population": 0.02,
          "title": "#fff"
        },
        "darkVibrant": {
          "_type": "sanity.imagePaletteSwatch",
          "background": "#133670",
          "foreground": "#fff",
          "population": 0,
          "title": "#fff"
        },
        "dominant": {
          "_type": "sanity.imagePaletteSwatch",
          "background": "#2a6cda",
          "foreground": "#fff",
          "population": 0.56,
          "title": "#fff"
        },
        "lightMuted": {
          "_type": "sanity.imagePaletteSwatch",
          "background": "#a8bcd6",
          "foreground": "#000",
          "population": 0.02,
          "title": "#fff"
        },
        "lightVibrant": {
          "_type": "sanity.imagePaletteSwatch",
          "background": "#7cb4fc",
          "foreground": "#000",
          "population": 0.01,
          "title": "#fff"
        },
        "muted": {
          "_type": "sanity.imagePaletteSwatch",
          "background": "#577297",
          "foreground": "#fff",
          "population": 0.2,
          "title": "#fff"
        },
        "vibrant": {
          "_type": "sanity.imagePaletteSwatch",
          "background": "#2a6cda",
          "foreground": "#fff",
          "population": 0.56,
          "title": "#fff"
        }
      },
      "thumbHash": "/fcBBgBgtut6Z4ZleJZ5Z4eoIK0okvc="
    },
    "mimeType": "image/png",
    "originalFilename": "NPM_upstream_tags.png",
    "path": "images/rafvlnhi/production/8310d84208e36f92aa5dfab9f059dd255a232934-755x923.png",
    "sha1hash": "8310d84208e36f92aa5dfab9f059dd255a232934",
    "size": 113103,
    "uploadId": "5f4f0b833485db939b348ecdf9d378b09314e00c",
    "url": "https://cdn.sanity.io/images/rafvlnhi/production/8310d84208e36f92aa5dfab9f059dd255a232934-755x923.png"
  },
  "link": {
    "_type": "link",
    "href": null,
    "openInNewTab": false
  },
  "markDefs": null
}
```



For more information, see [Upstream tag precedence](https://docs.cloudsmith.com/formats/npm-registry#upstream-tag-precedence) in the Cloudsmith documentation.