Addition of "extends" top level property to enable simple configuration inheritance

Problem

Multiple teams collaborating on a common codebase may have different dependency or setup needs and currently this is done by sharing a single devcontainer.json configuration with all of their individual needs combined. #6 describes support for multiple configuration files, but there isn't set a way to consolidate the shared configuration into a single file.

Proposed Solution

Introduce a new top level key "extends" with a value that is a relative a file path within the same repository to a "parent" devcontainer configuration. The configurations will be merged using the same rules applied by a Docker Compose overrides file.

// .devcontainer/defaults.json
{
    "name": "example/project",
    "forwardPorts": [80, 5432],
    "hostRequirements": {
        "storage": "64gb",
        "memory": "16gb"
    }
}

// .devcontainer/devcontainer.json
{
    "extends": "./defaults.json",
    "forwardPorts": [2222],
    "hostRequirements": {
        "memory": "32gb"
    },
   "onCreateCommand": ".devcontainer/on-create-command.sh",
}

// Results in
{
    "name": "example/project",
    "forwardPorts": [80, 5432, 2222],    // <-- Array values are the UNION
    "hostRequirements": {
        "storage": "64gb",
        "memory": "32gb"                          // <-- Basic types overwrite
    },
   "onCreateCommand": ".devcontainer/on-create-command.sh",   // <-- New keys are added
}

where the value of "extends" is a relative path to a JSON or JSONC file in the same repository:

Same Directory: "./defaults.json"
Parent Director: "../defaults.json"
Subdirectory: "./dev/defaults.json"

Future

Add support for referring to configuration outside the repository

Users may have a use-case for keeping some shared configuration in a separate repository. The described solution does not support this, but support for this could be added.

Add support for JSON Schema/Open API 3.0 style "$ref" document imports

The described solution is opinionated about how to merge a document, which may not be a good fit for everyone's needs (see docker/compose#3729). A more sophisticated document reference method could be introduced to give users more control to import documents within objects or arrays and to reference objects within imported documents. See #23 for more details.

Users may have a use-case for keeping some shared configuration in a separate repository. The described solution does not support this, but support for this could be added.

Yeah I think this is a worthy thing to consider given microsoft/vscode-remote-release#3279. That said, it might require the result of #7 first since this could affect how you'd make these kinds of references. Agree that a first implementation could be local references to start particularly with that in mind.

In terms of the example though, it shows .devcontainer/project.json which wouldn't be auto-detected currently. I assume that would be either .devcontainer/devcontainer.json or follow the folder structure from #6?

In terms of the example though, it shows .devcontainer/project.json which wouldn't be auto-detected currently. I assume that would be either .devcontainer/devcontainer.json or follow the folder structure from #6?

That's right -- this is an oversight in the sample and wasn't mean to deviate from expecting that the file is named devcontainer.json. I'll update it.

toying around with a simple example repo: https://github.com/joshspicer/extends

sorry to be that guy but, is there any news on this topic ?

The main use I have for this is similar to #305: I have a project using a dev container which has a base image from our common registry. If I want to override that base image currently (for example to use an ARM image instead of x86-64), I have to edit devcontainer.json and remember not to commit the changes. It would be useful if I could have an override file which would change a Docker build argument but otherwise keep behaviour inline with everything else.

I have a situation where I'm dealing with 300+ repos and I am ideally looking to have this be a way to standardize and roll out updates to our teams development environment while being able to make repo specific overrides depending on project (software version, any strange config, etc).

It's working perfectly using the alternative repo configuration folder besides the fact that I can't abstract out any of the shared config so there's a ton of duplicated config and lot of room for things to drift project to project

We're trying to centralize our tooling and local build so onboarding both new staff and new projects is as easy as install Code, open the repo, and build the container when prompted.

Overrides would save me from duplicating config in hundreds of files

I'm hoping I'm missing something that already exists, but overrides seem to be the missing piece I've been looking for in the docs

I have same problem, multiple repos each one with their own isolated dev container. to be worked as standalone and a main repo/orchestrator for them all... The goal is to have only one extended docker-compose.yml and a extended devcontainer.json since the only thing i need to change on them is the:

"dockerComposeFile": "path/to/docker-compose.yml",

Right now i have to recreate multiple exact devcontainer.json to change this one line.

For my case i found the solution.

https://containers.dev/implementors/json_reference/

You can use LABEL dev.containers.metadata into the Dockerfile itself.

Simple config would be knowelege of the labeled files and what lays within each one,
Backup!
Sort!

Hi, as a maintainer of many (many) projects, I tend to maintains dozens of devcontainer configs which are differing just a little from each other.

The "extends" property will be perfect to have only few devcontainer base and extending for every projects.

Any news on this implementation?

This is how I solved this problem for myself, but an extends feature would still be useful.

The root devcontainer-common.json is a template with variable${localWorkspaceFolderBasename}. For any new project, create a symlink to this file in its .devcontainer folder as devcontainer.json.

All projects share the root docker-compose.yml and Dockerfile.

File Structure

/
├── devcontainer-common.json  # Template
├── docker-compose.yml        # Shared
├── Dockerfile                # Shared
│
├── project-a/
│   └── .devcontainer/
│       └── devcontainer.json   # -> ../../devcontainer-common.json
│
└── project-b/
    └── .devcontainer/
        └── devcontainer.json   # -> ../../devcontainer-common.json

Create project-b/.devcontainer.
Create a symlink: ln -s ../../devcontainer-common.json project-b/.devcontainer/devcontainer.json.

Example `devcontainer-common.json`

{
    "dockerComposeFile": [
        "../../docker-compose.yml"
    ],
    "extensions": [
        "ms-azuretools.vscode-docker"
    ],
    "features": {
        "ghcr.io/devcontainers/features/node:1": {
            "nvm": true,
            "version": "lts"
        }
    },
    "name": "🐳 ${localWorkspaceFolderBasename}",
    "remoteUser": "vscode",
    "service": "devcontainer",
    "settings": {
        "terminal.integrated.shell.linux": "/bin/bash"
    },
    "workspaceFolder": "/x/${localWorkspaceFolderBasename}"
}

refactor: use workspaceMount instead of unstable extends proposal

There seems to be a PR that has been opened since 2 years related to this.

Any chance we can reiterate on this change?

I've had to create an entire config merge pipeline for this purpose. I keep a collection of devcontainer configs in a separate repo. Most of them use basically the same devcontainer.json template but add little tweaks for each project. I've modeled devcontainer.json in Pydantic and I actually merge together configs to generate final devcontainer.json files from a common template.

It would be great to have this supported in the spec so I can get rid of all my jank.

Same problem here. I want to have a base spec that is also used by the CI and an extended one with some additional postCreateCommand and postStartCommand that take some time and only make sense for the devs but would significantly slow-down the CI.

I have a huge list of "customizations" (extensions and settings for vscode) that I share among multiple containers, and it would be nice to have a way to share it across them (they already use a common docker-compose file)

feat: add shared devcontainer layer consumable by other repos

Update for subscribers:
I'm working on my own open source project that utilizes devcontainers (super_projects). So I decided to pick this up and implement it.
Implementation/docs are in open PRs: CLI devcontainers/cli#1306 and spec #772. Feedback with the intention to get to where we can merge this feature is welcome.

Update for subscribers: I'm working on my own open source project that utilizes devcontainers (super_projects). So I decided to pick this up and implement it. Implementation/docs are in open PRs: CLI devcontainers/cli#1306 and spec #772. Feedback with the intention to get to where we can merge this feature is welcome.

I'd aim to get the spec maintainers from this repo involved at the earliest opportunity, or you risk doing the whole xkcd standards dance.

Chuck Lantz (@Chuxel)

Chuck Lantz (@Chuxel), joshspicer, Samruddhi Khandale (@samruddhikhandale), Christof Marti (@chrmarti), Dev containers Bot (@devcontainers-bot) Please arrange for someone to review this when possible. It is in the finalization stage and is already intended to be part of the spec. I adhered to the past pull request changes (albeit with the added extendsMergeMode specified in the PRs). So it mostly just needs a technical review of the implementation and an okay on that specification.
open PRs: CLI devcontainers/cli#1306 and spec #772.

Thanks for your support

Navigation Menu

Repository navigation

Addition of "extends" top level property to enable simple configuration inheritance #22

Problem

Proposed Solution

Future

Add support for referring to configuration outside the repository

Add support for JSON Schema/Open API 3.0 style "$ref" document imports

File Structure

Example `devcontainer-common.json`

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Addition of "extends" top level property to enable simple configuration inheritance #22

Description

Problem

Proposed Solution

Future

Add support for referring to configuration outside the repository

Add support for JSON Schema/Open API 3.0 style "$ref" document imports

Activity

Chuxel commented on Mar 30, 2022

greggroth commented on Mar 30, 2022

joshspicer commented on May 16, 2022

phorcys420 commented on Mar 5, 2024

acdha commented on Nov 5, 2024

cpqoc commented on Apr 25, 2025

holchan commented on May 10, 2025

holchan commented on May 12, 2025

Roboticsense00 commented on May 20, 2025

neilime commented on Nov 5, 2025

karpulix commented on Nov 11, 2025

File Structure

Example devcontainer-common.json

fsw0422 commented on Dec 11, 2025

medley56 commented on Apr 9, 2026

Falco20019 commented on Apr 14, 2026

thebitbesi commented on May 4, 2026

SamuelFrost commented on Sep 24, 2026

aioue commented on Sep 24, 2026

SamuelFrost commented on Sep 28, 2026

molabasehiwe-jpg commented on Oct 15, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Example `devcontainer-common.json`