Repository navigation
Addition of "extends" top level property to enable simple configuration inheritance #22
Description
Activity
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.jsonwhich wouldn't be auto-detected currently. I assume that would be either.devcontainer/devcontainer.jsonor 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.Reacted by Chuck Lantztoying around with a simple example repo: https://github.com/joshspicer/extends
sorry to be that guy but, is there any news on this topic ?
Reacted by Ian, BenM, Troy Gibb, Alex Malkevich, Mateus Deitos, Jonas Lundberg, Jordan Corbett-Frank, Albert Clèrigues, Daniel Jünger, Mark Harris and 69 moreThe 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.jsonand 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.Reacted by John M Daly, Tim, Juanmi Jaime Montero, ryanpodonnell1, Paul Kozin, David Sisco, Christopher McClellan, Niko Föhr and MatiI 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
Reacted by Dan LaManna, Caleb Evans, Samuel Weibel, Claudio Catterina, Jaap Roes, joshdunnlime, holchan, ccasn, Jason Sipula, Steven Maude and 1 moreI 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.
Reacted by Caleb Evans, holchan, cpqoc, Christian Ciach and Dan LaMannaFor my case i found the solution.
https://containers.dev/implementors/json_reference/
You can use LABEL dev.containers.metadata into the Dockerfile itself.
Reacted by Artem BaguinskiSimple 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?
Reacted by janw, Alexander Karpov and thebitbesiThis is how I solved this problem for myself, but an
extendsfeature would still be useful.The root
devcontainer-common.jsonis a template with variable${localWorkspaceFolderBasename}. For any new project, create a symlink to this file in its.devcontainerfolder asdevcontainer.json.All projects share the root
docker-compose.ymlandDockerfile.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}" }- Create
- added a commit that references this issue
on Nov 12, 2025 There seems to be a PR that has been opened since 2 years related to this.
Any chance we can reiterate on this change?
Reacted by Emilien Escalle, Simon Kurtz, Avyan Kandasamy, Afonso, Steven Maude, Achille Verheye, Oana Schipor, Michael Wechner and Xanthus WongI'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.
Reacted by Emilien Escalle, grantsohn, Benjamin Krämer, Tom Paine and Martin O'LearySame problem here. I want to have a base spec that is also used by the CI and an extended one with some additional
postCreateCommandandpostStartCommandthat 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)
Reacted by thebit94dev, Emilien Escalle, ccasn, Anlanther, Artiom Diomin, Stanislau Kviatkouski and Sam Frost- added 2 commits that reference this issue
on Aug 14, 2026 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.Reacted by Emilien Escalle, seratg and Alex Godoy WolffUpdate 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.
Reacted by Simon Kurtz, Sam Frost and Alex Godoy WolffChuck 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.
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.jsonconfiguration 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.where the value of "extends" is a relative path to a JSON or JSONC file in the same repository:
"./defaults.json""../defaults.json""./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.