What's the difference between Renovate's depName and packageName?

Update 2025-05-27: this is now documented upstream (via)

Something I come up against, every so often, is trying to explain the difference between Renovate's depNames and packageNames.

Looking back at previous times I've looked at this, I seem to have had mixed answers to this question, and so I thought this was the right time to sit down and get my mental model correctly.

For instance, looking back at an (unmerged) PR I raised internally a few months ago:

chore(renovate): use `packageNames` over `depNames`

`depName` is intended to be a human-readable version of the
`packageName`, and although it usuaully matches exactly, there will be
some packages that have a different `depName` to `packageName`.

This made a change such as:

+"matchDepNames": [
-"matchPackageNames": [

But this was not correct to do 😅 If this was merged, it would actually have silently broken the Renovate configuration for the repo, as we'd no longer be correctly matching the packages we were looking at.

What's the difference?

The Renovate docs note that:

• depName: The name of the dependency being updated
• packageName: The full name that was used to look up the dependency

Renovate deems the depName as the "user facing" dependency name, and will present the dependency name in commit messages/Pull Requests/Merge Requests.

In a lot of cases, these two are exactly the same thing - but sometimes they don't match.

For a more practical example, let's look at the following Gradle plugin definition:

plugins {
    id("com.gradle.develocity").version("3.18.1")
}

In this case, depName=com.gradle.develocity, as that's the user-facing dependency name.

However, under the hood Renovate will map this to the packageName: com.gradle.develocity:com.gradle.develocity.gradle.plugin, which matches how it looks up the package in the Gradle Plugin Portal's Maven repository.

How do I know what depName and packageName are set to for a given package?

As noted, you'll generally be using the depName, as that's exposed to you as the human user of Renovate, and so it's straightforward to rely upon that.

You can assume that depName will be the name of the package you've defined - for instance depName=com.gradle.develocity, or depName=alpine for the below:

FROM alpine:latest

If you want more control and insight into your Renovate data, it is also worth digging into your debug logs.

If you're running self-hosted, that's an exercise left to the reader, but if you're running on the Mend Renovate Community Cloud, you're able to see the logs in your dashboard.

Look for a log line such as:

DEBUG: packageFiles with updates

{
  "config": {
    "gradle": [
      {
        "datasource": "maven",
        "deps": [
          {
            // ...
            "datasource": "maven",
            "depName": "com.gradle.develocity",
            "depType": "plugin",
            // ...
            "packageName": "com.gradle.develocity:com.gradle.develocity.gradle.plugin",
            "packageScope": "com.gradle.develocity",
            "registryUrl": "https://plugins.gradle.org/m2",
            "registryUrls": [
              "https://plugins.gradle.org/m2/"
            ],
            "updates": [
              // ...
            ],
            "versioning": "gradle",
            "warnings": [

            ]
          }
        ],
        "packageFile": "settings.gradle.kts"
      },
    ]
  }
}

This then gives you the depName and the packageName (and a whole host of other valuable data!)

You can also get this data when using Renovate's report exports, or using a tool such as renovate-graph.

Which should I use?

It's very likely that you will only need to worry about depNames, and therefore only use things like matchDepNames.

However, there may be cases that you need to delve a little deeper into the config to make it work with matchPackageNames, but that shouldn't be that often!

Through discussion on the Renovate developers' Slack, I stand corrected.

It's likely that depName and matchDepNames will be the starting point, but that depending on package ecosystems you're working with, how you're hosting/proxying dependencies, or many other possible reasons - you may need to use packageName and matchPackageNames.

As with many great things in the industry - "it depends".