Skip to content

Workspace metadata

uv workspace metadata exports the information uv has about your workspace as JSON so other tools can use it. In particular, if you want access to the information in a uv.lock, you should prefer this command's output, as uv.lock is not a stable format we guarantee anything about.

The primary structure is the "resolution" field which contains the dependency graph with exact package versions that a uv.lock encodes.

The edges of the graph are the dependencies every node defines. These are the things that must also be installed for it to be installed (and their dependencies recursively, keeping in mind that cycles are perfectly normal to encounter in this graph). Each dependency entry will include an id for the node it refers to, and an optional marker that specifies on what platforms the dependency is required (if there is no marker the dependency is always required).

Nodes in the graph are uniquely identified by package name, version, source, and kind.

There are 3 kinds of node in the graph:

  • "package" -- the package itself
  • { "extra": "extraname" } -- an extra the package defines
  • { "group": "groupname" } -- a dependency group the package defines

(In the future we will add "build" nodes for the dependencies of build environments.)

If you want to install mypackage, find its "kind": "package" node. This node will also include information on its sdist, its wheels, its extras (optional_dependencies), and dependency groups (dependency_groups).

If you want to install mypackage[myextra] then find the node with "kind": { "extra": "myextra" } for mypackage (this node will always depend on mypackage). If you want to install mypackage[extra1, extra2], find the two nodes for mypackage[extra1] and mypackage[extra2].

If you want to install the dependency group mypackage:mygroup then find the node with "kind": { "group": "mygroup" } for mypackage (this node will not depend on mypackage, as dependency groups are just lists of things you might want when working on the package itself).

Handling multiple versions of a package

Two versions of a package cannot be installed into a python environment, but the dependency graph may still include multiple versions of a package. This can happen for two different reasons.

The first way is for different platforms to have conflicting requirements that force different versions of a package to be used.

The second way is when a workspace has conflicts, implying some workspace members or their extras are mutually exclusive, and only one of them can be installed at a time. Information about conflicts can be found in the top-level conflicts field.

The specific guarantee we provide is that for any concrete choice of markers, if you select a set of packages to install that has no conflicts, then the resulting set of packages to install will not have multiple versions of a package.

If you just want to get "every version of pydantic this workspace uses" you're free to iterate through the list of nodes and collect up every instance. If however you want to specifically analyze the graph and get actual resolutions you will likely need to consult conflicts and need to understand how to resolve markers for a specific platform.

The best way to avoid mistakes when working with multiple versions of a package is to keep your queries into the dependency graph rooted in operations on workspace members, as those are the natural entry-points to the graph that uv wants to work on, and can give coherent responses for: "install member1 and member2[extra]".

Another way to put this is that when possible you should avoid iterating over the resolution object to find a node. Only access resolution like a map using ids that were provided by another part of the metadata. The only ids this initially gives you access to are the ones listed in the members array, which lists all the workspace members. From there you may find the ids of that package's dependencies, extras, and dependency groups and recursively discover other packages.

So rather than trying to find a node for anyio in the dependency graph directly, you should decide what workspace member(s) you're interested in analyzing as if they were going to be installed. While traversing the dependencies of the things you want to install, you may visit an instance of anyio, which is the one you should use. If you visit multiple instances of anyio then that means you've selected a conflicting set of things to install which uv would never select.

So if you wanted to analyze say, installing the dev dependency group of the workspace member mypackage it would look something like:

member = find_by_name(metadata.members, "mypackage")
member_node = metadata.resolution[member.id]
group = find_by_name(member_node.dependency_groups, "dev")
group_node = metadata.resolution[group.id]
visit(metadata, [group_node])

If you wanted to analyze two particular workspace members installed together, it would look something like:

to_analyze = []
for member_name in ["package1", "package2"]:
  member = find_by_name(metadata.members, member_name)
  member_node = metadata.resolution[member.id]
  to_analyze.append(member_node)
visit(metadata, to_analyze)

Where visit is your favourite graph traversal algorithm like depth-first-search:

def visit(metadata: UvMetadata, to_analyze: list[Node]):
  visited = set()
  while len(to_analyze) > 0:
    node = to_analyze.pop()

    # Handle cycles by avoiding revisiting nodes
    if node.id in visited:
      continue
    visited.add(node.id)

    # We also need to analyze its dependencies
    for dependency in node.dependencies:
      # Only follow edges if they satisfy the desired platform's markers
      if dependency.marker and not satisfies(platform, dependency.marker):
        continue
      to_analyze.append(metadata.resolution[dependency.id])

    # Analyze any package node we encounter
    if node.kind == "package":
      print(node.name, node.version, node.source)

Schema

A full JSON schema for the format will be provided when the format is finalized.

Here is a human-readable annotated example:

{
    // Information about the schema of this output
    "schema": {
        // The version of this output, currently "preview"
        "version": "preview"
    },
    // The directory the uv.lock can be found in
    "workspace_root": "/workspace",
    // Any requirements on the python version this workspace has
  //
  // `marker` fields all have this as an implicit constraint that is omitted for cleanliness
    "requires_python": ">=3.12",
    // A list of workspace members
    "members": [
    {
      // The name of the package
      "name": "mypackage",
      // The directory that contains its pyproject.toml
      "path": "/workspace/packages/mypackage",
      // The id of this package's info in the `resolution` map below
      "id": "mypackage==0.1.0@editable+/workspace/packages/mypackage"
    },
    ],
  // A list-of-sets of workspace items that are mutually-exclusive to install,
  // presumably because they need to install different versions of the same package.
  //
  // Any attempt to install two things that belong to the same set must be rejected.
  //
  // There are 3 kinds of item:
  //
  // * Project -- "kind": "project"
  // * Extra   -- "kind": { "extra": "extraname" }
  // * Group   -- "kind": { "group": "groupname" }
  "conflicts": {
    "sets": [
      {
        "items": [
          {
            "package": "mypackage",
            "kind": { "extra": "myextra" }
            "id": "mypackage[myextra]==0.1.0@editable+/workspace/packages/mypackage",
          }
          {
            "package": "mypackage",
            "kind": { "group": "mygroup" }
            "id": "mypackage:mygroup==0.1.0@editable+/workspace/packages/mypackage",
          }
        ]
      }
    ]
  }
  // Resolved information about packages and dependencies.
  //
  // Each entry in this map is a node in the dependency graph. There are currently
  // 3 kinds of node in the dependency graph, although more are planned in the future.
  //
  // * Packages -- "kind": "package"
  // * Extras   -- "kind": { "extra": "extraname" }
  // * Groups   -- "kind": { "group": "groupname" }
  //
  // Package nodes contain most of the metadata, while other nodes are mostly just a list
  // of dependencies. The different kinds of node are included like this to encourage correct
  // analysis of the graph. For instance, a node for `mypackage[someextra]` always depends on
  // `mypackage`, while `mypackage:somegroup` does not (because dependency-groups are just a
  // list of packages you might want to install while working on `mypackage`). Sugars like
  // `mypackage[extra1, extra2]` are decomposed into separate dependencies on `mypackage[extra1]`
  // and `mypackage[extra2]`.
  //
  // The ids used here are human-readable but should be handled as opaque (the nodes contain
  // the same information in a more convenient form).
  "resolution": {

    // This node is a workspace member
    "mypackage==0.1.0@editable+/workspace/packages/mypackage": {
      // The name of the package
      "name": "mypackage",
      // The version of the package (this may be missing, as source trees do not need versions)
      "version": "0.1.0",
      // The source of the package, in this case it's an editable whose path relative to the
      // `workspace_root` is `./packages/mypackage`
      "source": {
        "editable": "/workspace/packages/mypackage"
      },
      // The kind of the node, in this case "package" (see the docs on `resolution` above for details)
      "kind": "package",
      // The dependencies that must be installed to also install this node into an environment
      "dependencies": [
        {
          // The id of the node to lookup for details
          "id": "iniconfig==2.0.0@registry+https://pypi.org/simple"
          "marker": "marker": "sys_platform == 'linux'"
        }
      ],
      // The extras that this package defines
      "optional_dependencies": [
        {
          "name": "myextra",
          "id": "mypackage[myextra]==0.1.0@editable+/workspace/packages/mypackage"
        }
      ],
      // The dependency groups this package defines
      "dependency_groups": [
        {
          "name": "mygroup",
          "id": "mypackage:mygroup==0.1.0@editable+/workspace/packages/mypackage"
        }
      ]
    },

    // This node is an extra on a workspace member
    "mypackage[myextra]==0.1.0@editable+/workspace/packages/mypackage": {
      // These fields will match the package node above
      "name": "mypackage",
      "version": "0.1.0",
      "source": {
        "editable": "/workspace/packages/mypackage"
      },
      // But these two will differ from the package node above
      "kind": { "extra": "myextra" },
      "dependencies": [
        {
          "id": "mypackage==0.1.0@editable+/workspace/packages/mypackage"
        }
        {
          "id": "anyio==2.0.0@registry+https://pypi.org/simple"
        }
      ]
    },

    // This node is a dependency-group on a workspace member
    "mypackage:mygroup==0.1.0@editable+/workspace/packages/mypackage": {
      // These fields will match the package node above
      "name": "mypackage",
      "version": "0.1.0",
      "source": {
        "editable": "/workspace/packages/mypackage"
      },
      // But these two will differ from the package node above
      "kind": { "extra": "myextra" },
      "dependencies": [
        {
          "id": "anyio==1.0.0@registry+https://pypi.org/simple"
        }
      ]
    },

    // This node is a package on pypi
    "iniconfig==2.0.0@registry+https://pypi.org/simple": {
      "name": "iniconfig",
      "version": "2.0.0",
      // registry sources look like this
      "source": {
        "registry": {
          "url": "https://pypi.org/simple"
        }
      },
      "kind": "package",
      "dependencies": [],
      // Details on the package's source distribution
      "sdist": {
        // May alternatively be `path`
        "url": "https://files.pythonhosted.org/packages/d7/4b/cbd8e699e64a6f16ca3a8220661b5f83792b3017d0f79807cb8708d33913/iniconfig-2.0.0.tar.gz",
        "hashes": {
          "sha256": "2d91e135bf72d31a410b17c16da610a82cb55f6b0477d1a902134b24a455b8b3"
        },
        "size": 4646,
        "upload_time": "2023-01-07T11:08:11.254Z"
      },
      // The wheels we found for this package
      "wheels": [
        {
          // May alternatively be `path`
          "url": "https://files.pythonhosted.org/packages/ef/a6/62565a6e1cf69e10f5727360368e451d4b7f58beeac6173dc9db836a5b46/iniconfig-2.0.0-py3-none-any.whl",
          "hashes": {
            "sha256": "b6a85871a79d2e3b22d2d1b94ac2824226a63c6b741c88f7ae975f18b6778374"
          },
          "size": 5892,
          "upload_time": "2023-01-07T11:08:09.864Z",
          // Parsing this name is how you know what platform a wheel supports
          "filename": "iniconfig-2.0.0-py3-none-any.whl"
        }
      ]
    }

    // ...and so on
    "anyio==1.0.0@registry+https://pypi.org/simple": { ... }
    "anyio==2.0.0@registry+https://pypi.org/simple": { ... }
  }
}