---
title: "Using matrix jobs"
description: "\"A how to guide for using matrix jobs to simplify your CircleCI configuration.\""
platform: "Cloud, Server"
doc_version: "Server"
last_updated: "2026-10-06"
---

> For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md).
>
> For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt).

# Using matrix jobs

Matrix jobs provide a way to run a job multiple times with arguments that are supplied using parameters. An example of this is configuring testing on multiple operating systems and against different language or library versions.

## Use matrix jobs to run multiple OS tests

In the following example, the `test` job runs across a Linux Docker container and a Linux VM. It uses two different versions of Node.js. On each run of the `test` job, different parameters are passed to set the OS and Node.js version:

**Using Docker?** Authenticating Docker pulls from image registries is recommended when using the Docker execution environment. Authenticated pulls allow access to private Docker images, and may also grant higher rate limits, depending on your registry provider. For further information, see [Using Docker Authenticated Pulls](https://circleci.com/docs/guides/execute/private-images/).

```yaml
version: 2.1

orbs:
  node: circleci/node@4.7

executors:
  docker: # Docker using the Base Convenience Image
    docker:
      - image: cimg/base:stable
  linux: # a Linux VM
    machine:
      image: default

jobs:
  test:
    parameters:
      os:
        type: executor
      node-version:
        type: string
    executor: << parameters.os >>
    steps:
      - checkout
      - node/install:
          node-version: << parameters.node-version >>
          install-yarn: true

workflows:
  all-tests:
    jobs:
      - test:
          matrix:
            parameters:
              os: [docker, linux]
              node-version: ["14.17.6", "16.9.0"]
```

### List jobs that will run

The expanded version of this matrix runs the following list of jobs under the `all-tests` workflow:

```yaml
    - test-14.17.6-docker
    - test-16.9.0-docker
    - test-14.17.6-linux
    - test-16.9.0-linux
```

## Next steps

For full details of the matrix jobs specification, see the [Configuration Reference](https://circleci.com/docs/reference/configuration-reference/#matrix).