In an Azure Pipelines pool: block, what is the difference between setting vmImage and setting name together with demands?

## `pool` selects where a job runs Because the job is the unit an agent is allocated to, `pool` is fundamentally a job-level property, even though you may write it once at the root or on a stage as an inherited default. A job-level `pool` overrides whatever it inherited, so one stage can happily run a Linux job and a Windows job side by side. ```yaml jobs: - job: Linux pool: vmImage: ubuntu-latest steps: [ { script: uname -a } ] - job: Windows pool: vmImage: windows-latest steps: [ { powershell: $PSVersionTable } ] ``` ## `vmImage`: Microsoft-hosted Naming a `vmImage` requests an agent from Microsoft's hosted pool. Azure creates a virtual machine from the named image, runs exactly one job on it, and destroys it afterwards. Image names include `ubuntu-latest`, `windows-latest` and `macos-latest`, plus pinned variants such as `ubuntu-22.04` — and pinning is worth doing, because `*-latest` moves when Microsoft rotates the image, which is a routine source of "nothing changed and the build broke". What you get: a maintained toolchain, no machines to patch, and a genuinely clean starting state every time. What you give up: control of the installed software, the machine's size, and any network position — a hosted agent sits on Microsoft's network and cannot see a private subnet unless you deliberately build a path to it. One more thing hosted agents lack is `demands` in any meaningful sense: the image *is* the selector. ## `name` plus `demands`: your own pool ```yaml pool: name: LinuxBuilders demands: - docker # capability must exist - Agent.OS -equals Linux # capability must equal a value ``` Here you are choosing a pool of agents you registered and maintain. Each agent publishes a set of **capabilities**: - **System capabilities** are discovered by the agent when it starts — the operating system, the architecture, environment variables, and the presence of certain installed tools. They refresh when the agent restarts. - **User-defined capabilities** are key/value pairs you add to a specific agent in the pool's settings, and they exist precisely so you can express things the agent cannot discover: `gpu=true`, `licence=matlab`, `network=pci-zone`. A **demand** is a predicate over those capabilities, and the grammar is deliberately tiny: | Form | Meaning | |---|---| | `myCapability` | the capability exists, with any value | | `myCapability -equals value` | the capability exists and equals exactly this string | That is the whole language. There is no numeric comparison, no negation, no `contains`, and none of the expression functions you can use in a `condition:`. Anything more expressive has to be encoded into the capability value itself, or handled by splitting the pool. ## The failure mode worth knowing Demands are a *scheduling filter*, not a validation step. If you demand a capability that no agent in the pool reports — a typo, a capability set on a machine that has since been decommissioned, an agent that has not been restarted since the tool was installed — the job is not rejected. It goes to the queue and waits for an agent that will never appear, until the job's wait exceeds its timeout and it fails. So the symptom is a job stuck at "waiting for an available agent", and the diagnosis is to open the agent pool, look at an agent's **Capabilities** tab, and compare it letter by letter with the demand. Capability names and values are matched exactly. A related trap: installing a tool on a self-hosted agent does not update its capabilities until the agent process restarts, so the demand keeps failing on a machine that visibly has the tool. ## Choosing between them Reach for a self-hosted pool with demands when a job needs something a hosted image cannot give: private network access to an internal artifact store or database, specialised hardware, a licensed tool, unusually large disk or memory, or a warm dependency cache that makes builds materially faster. Otherwise the hosted image is almost always the better default, because a fresh machine per job removes an entire category of "works on the build server" problems, and because the machines are somebody else's responsibility to patch. A common middle ground is to run most jobs on `vmImage` and reserve a small self-hosted pool, addressed by demand, for the two or three jobs that genuinely need it.