Development Container Features are self-contained, shareable units of installation code and development container configuration. The name comes from the idea that referencing one of them allows you to quickly and easily add more tooling, runtime, or library “features” into your development container for you or your collaborators to use.
Feature metadata is captured by adevcontainer-feature.json file in the root folder of the feature.
Note: While Features may be installed on top of any base image, the implementation of a Feature might restrict it to a subset of possible base images. For example, some Features may be authored to work with a certain Linux distro (e.g. debian-based images that use the
aptpackage manager).This page covers details on the Features specification. If you are looking for summarized information on creating your own Features, check out thequick start andcore Features repositories.
A Feature is a self contained entity in a folder with at least adevcontainer-feature.json andinstall.sh entrypoint script. Additional files are permitted and are packaged along side the required files.
+-- feature| +-- devcontainer-feature.json| +-- install.sh| +-- (other files)Thedevcontainer-feature.json file defines metadata about a given Feature.
All properties are optionalexcept forid,version, andname.
devContainerFeature.schema.json defines the schema for thedevcontainer-feature.json file.
The properties of the file are as follows:
| Property | Type | Description |
|---|---|---|
id | string | Required: Identifier of the Feature. Must be unique in the context of the repository where the Feature exists and must match the name of the directory where thedevcontainer-feature.json resides. |
version | string | Required: The semantic version of the Feature (e.g:1.0.0). |
name | string | Required: A “human-friendly” display name for the Feature. |
description | string | Description of the Feature. |
documentationURL | string | Url that points to the documentation of the Feature. |
licenseURL | string | Url that points to the license of the Feature. |
keywords | array | List of strings relevant to a user that would search for this definition/Feature. |
options | object | A map of options that will be passed as environment variables to the execution of the script. |
containerEnv | object | A set of name value pairs that sets or overrides environment variables. |
privileged | boolean | Setsprivileged mode for the container (required by things like docker-in-docker) when the feature is used. |
init | boolean | Adds thetiny init process to the container (--init) when the Feature is used. |
capAdd | array | Adds containercapabilities when the Feature is used. |
securityOpt | array | Sets container security options like updating theseccomp profile when the Feature is used. |
entrypoint | string | Set if the feature requires an “entrypoint” script that should fire at container start up. |
customizations | object | Product specific properties, each namespace undercustomizations is treated as a separate set of properties. For each of this sets the object is parsed, values are replaced while arrays are set as a union. |
dependsOn | object | An object (**) of Feature dependencies thatmust be satisified before this Feature is installed. Elements follow the same semantics of thefeatures object indevcontainer.json.SeeInstallation Order for further information. |
installsAfter | array | Array of ID’s of Features (omitting a version tag) that should execute before this one. Allows control for Feature authors on soft dependencies between different Features.SeeInstallation Order for further information. |
legacyIds | array | Array of old IDs used to publish this Feature. The property is useful for renaming a currently published Feature within a single namespace. |
deprecated | boolean | Indicates that the Feature is deprecated, and will not receive any further updates/support. This property is intended to be used by the supporting tools for highlighting Feature deprecation. |
mounts | object | Defaults to unset. Cross-orchestrator way to add additional mounts to a container. Each value is an object that accepts the same values as theDocker CLI--mount flag. The Pre-defineddevcontainerId variable may be referenced in the value. For example:"mounts": [{ "source": "dind-var-lib-docker", "target": "/var/lib/docker", "type": "volume" }] |
(**) The ID must refer to either a Feature (1) published to an OCI registry, (2) a Feature Tgz URI, or (3) a Feature in the local file tree. Deprecated Feature identifiers (i.e GitHub Release) are not supported and the presence of this property may be considered a fatal error or ignored. Forlocal Features (ie: during development), you may also depend on other local Features by providing a relative path to the Feature, relative to folder containing the activedevcontainer.json. This behavior of Features within this property again mirror thefeatures object indevcontainer.json.
The following lifecycle hooks may be declared as properties ofdevcontainer-feature.json.
| Property | Type |
|---|---|
onCreateCommand | string, array, object |
updateContentCommand | string, array, object |
postCreateCommand | string, array, object |
postStartCommand | string, array, object |
postAttachCommand | string, array, object |
Each property mirrors the behavior of the matching property indevcontainer.json, including the behavior that commands are executed from the context of theproject workspace folder.
For each lifecycle hook (inFeature installation order), each command contributed by a Feature is executed in sequence (blocking the next command from executing). Commands provided by Features are always executedbefore any user-provided lifecycle commands (i.e: in thedevcontainer.json).
If a Feature provides a given command with theobject syntax, all commands within that group are executed in parallel, but still blocking commands from subsequent Features and/or thedevcontainer.json.
Note: These properties are stored withinimage metadata.
It may be helpful for a Feature to write scripts to a known, persistent path within the container (i.e. for later use in a given lifecycle hook).
Take for instance thegit-lfs Feature, whichwrites a script to/usr/local/share/pull-git-lfs-artifacts.sh during installation.
PULL_GIT_LFS_SCRIPT_PATH="/usr/local/share/pull-git-lfs-artifacts.sh"tee"$PULL_GIT_LFS_SCRIPT_PATH"> /dev/null\<<EOF#!/bin/shset -e<...truncated...>EOFThis script is then executed during thepostCreateCommand lifecycle hook.
{"id":"git-lfs","version":"1.1.0","name":"Git Large File Support (LFS)",// <...truncated...>"postCreateCommand":"/usr/local/share/pull-git-lfs-artifacts.sh","installsAfter":["ghcr.io/devcontainers/features/common-utils"]}options propertyThe options property contains a map of option IDs and their related configuration settings. The ID becomes the name of the environment variable in all caps. Seeoption resolution for more details. For example:
{"options":{"optionIdGoesHere":{"type":"string","description":"Description of the option","proposals":["value1","value2"],"default":"value1"}}}| Property | Type | Description |
|---|---|---|
optionId | string | ID of the option that is converted into an all-caps environment variable with the selected value in it. |
optionId.type | string | Type of the option. Valid types are currently:boolean,string |
optionId.proposals | array | A list of suggested string values. Free-form valuesare allowed. Omit when usingoptionId.enum. |
optionId.enum | array | A strict list of allowed string values. Free-form values arenot allowed. Omit when usingoptionId.proposals. |
optionId.default | string or boolean | Default value for the option. |
optionId.description | string | Description for the option. |
Feature scripts run as theroot user and sometimes need to know which user account the dev container will be used with.
_REMOTE_USER and_CONTAINER_USER environment variables are passsed to the Features scripts with_CONTAINER_USER being the container’s user and_REMOTE_USER being the configuredremoteUser. If noremoteUser is configured,_REMOTE_USER is set to the same value as_CONTAINER_USER.
Additionally, the home folders of the two users are passed to the Feature scripts as_REMOTE_USER_HOME and_CONTAINER_USER_HOME environment variables.
The container user can be set withcontainerUser in thedevcontainer.json and image metadata,user in thedocker-compose.yml,USER in the Dockerfile, and can be passed down from the base image.
An identifier will be referred to as${devcontainerId} in thedevcontainer.json and the Feature metadata and that will be replaced with the dev container’s id. It should only be used in parts of the configuration and metadata that is not used for building the image because that would otherwise prevent pre-building the image at a time when the dev container’s id is not known yet. Excluding boolean, numbers and enum properties the properties supporting${devcontainerId} in the Feature metadata are:entrypoint,mounts,customizations.
Implementations can choose how to compute this identifier. They must ensure that it is unique among other dev containers on the same Docker host and that it is stable across rebuilds of dev containers. The identifier must only contain alphanumeric characters. We describe a way to do this below.
The following assumes that a dev container can be identified among other dev containers on the same Docker host by a set of labels on the container. Implementations may choose to follow this approach.
The identifier is derived from the set of container labels uniquely identifying the dev container. It is up to the implementation to choose these labels. E.g., if the dev container is based on a local folder the label could be nameddevcontainer.local_folder and have the local folder’s path as its value.
E.g., theghcr.io/devcontainers/features/docker-in-docker Feature could use the dev container id with:
{"id":"docker-in-docker","version":"1.0.4",// ..."mounts":[{"source":"dind-var-lib-docker-${devcontainerId}","target":"/var/lib/docker","type":"volume"}]}JavaScript implementation taking an object with the labels as argument and returning a string as the result:
constcrypto=require('crypto');functionuniqueIdForLabels(idLabels){conststringInput=JSON.stringify(idLabels,Object.keys(idLabels).sort());// sort propertiesconstbufferInput=Buffer.from(stringInput,'utf-8');consthash=crypto.createHash('sha256').update(bufferInput).digest();constuniqueId=BigInt(`0x${hash.toString('hex')}`).toString(32).padStart(52,'0');returnuniqueId;}Features are referenced in a user’sdevcontainer.json under the top levelfeatures object.
A user can specify an arbitrary number of Features. At build time, these Features will be installed in an order defined by a combination of theinstallation order rules and implementation.
A single Feature is provided as a key/value pair, where the key is the Feature identifier, and the value is an object containing “options” (or empty for “default”). Each key in the feature object must be unique.
These options are sourced as environment variables at build-time, as specified inOption Resolution.
Below is a validfeatures object provided as an example.
"features":{"ghcr.io/user/repo/go":{},"ghcr.io/user/repo1/go:1":{},"ghcr.io/user/repo2/go:latest":{},"https://github.com/user/repo/releases/devcontainer-feature-go.tgz":{"optionA":"value"},"./myGoFeature":{"optionA":true,"optionB":"hello","version":"1.0.0"}}Note: The
:latestversion annotation is added implicitly if omitted. To pin to a specific package version (example), append it to the end of the Feature.
An option’s value can be provided as either astring orboolean, and should match what is expected by the feature in thedevcontainer-feature.json file.
As a shorthand, the value of thefeatures property can be provided as a single string. This string is mapped to an option calledversion. In the example below, both examples are equivalent.
"features":{"ghcr.io/owner/repo/go":"1.18"}"features":{"ghcr.io/owner/repo/go":{"version":"1.18"}}Theid format specified dicates how a supporting tool will locate and download a given feature.id is one of the following:
| Type | Description | Example |
|---|---|---|
<oci-registry>/<namespace>/<feature>[:<semantic-version>] | Reference to feature in OCI registry(*) | ghcr.io/user/repo/goghcr.io/user/repo/go:1ghcr.io/user/repo/go:latest |
https://<uri-to-feature-tgz> | Direct HTTPS URI to a tarball. | https://github.com/user/repo/releases/devcontainer-feature-go.tgz |
./<path-to-feature-dir> | A relative directory(**) to folder containing a devcontainer-feature.json. | ./myGoFeature |
(*) OCI registry must implement theOCI Artifact Distribution Specification. Some implementors can befound here.
(**) The provided path is always relative to the folder containing thedevcontainer.json. Further requirements are outlined in theLocally Referenced Addendum.
Each Feature is individuallyversioned according to the semver specification. Theversion property in the respectivedevcontainer-feature.json file is updated to increment the Feature’s version.
Tooling that handles releasing Features will not republish Features if that exact version has already been published; however, tooling must republish major and minor versions in accordance with the semver specification.
Features can be authored in a number of languages, the most straightforward being bash scripts. If a Feature is authored in a different language, information about it should be included in the metadata so that users can make an informed choice about it.
Reference information about the application required to execute the Feature should be included indevcontainer-feature.json in the metadata section.
Applications should default to/bin/sh for Features that do not include this information.
If the Feature is included in a folder as part of the repository that containsdevcontainer.json, no other steps are necessary.
For information on distributing Features, see theFeatures distribution page.
install.shTheinstall.sh script for each Feature should be executed asroot during a container image build. This allows the script to add needed OS dependencies or settings that could not otherwise be modified. This also allows the script to switch into another user’s context using thesu command (e.g.,su ${USERNAME} -c "command-goes-here"). In combination, this allows both root and non-root image modifications to occur even ifsudo is not present in the base image for security reasons.
To ensure that the appropriate shell is used, the execute bit should be set oninstall.sh and the file invoked directly (e.g.chmod +x install.sh && ./install.sh).
Note: It is recommended that Feature authors write
install.shusing a shell available by default in their supported distributions (e.g.,bashin Debian/Ubuntu or Fedora,shin Alpine). In the event a different shell is required (e.g.,fish),install.shcan be used to boostrap by checking for the presence of the desired shell, installing it if needed, and then invoking a secondary script using the shell.The
install.shfile can similarly be used to bootstrap something written in a compiled language like Go. Given the increasing likelihood that a Feature needs to work on both x86_64 and arm64-based devices (e.g., Apple Silicon Macs),install.shcan detect the current architecture (e.g., using something likeuname -mordpkg --print-architecture), and then invoke the right executable for that architecture.
By default, Features are installed on top of a base image in an order determined as optimal by the implementing tool.
If any of the following properties are provided in the Feature’sdevcontainer-feature.json, or the user’sdevcontainer.json, the order indicated by these propert(ies) are respected.
dependsOn property defined as a part of a Feature’sdevcontainer-feature.json.installsAfter property defined as part of a Feature’sdevcontainer-feature.json.overrideFeatureInstallOrder property in user’sdevcontainer.json. Allows users to control the order of execution of their Features.The optionaldependsOn property indicates a set of required, “hard” dependencies for a given Feature.
ThedependsOn property is declared in a Feature’sdevcontainer-feature.json metadata file. Elements of this property mirror the semantics of thefeatures object indevcontainer.json. Therefore, all dependencies may provide the relevant options, or an empty object (eg:"bar:123": {}) if the Feature’s default options are sufficient. Identical Features that provide different options are treated asdifferent Features (seeFeature equality for more info).
All Features indicated in thedependsOn propertymust be satisfied (a Featureequal to each dependency is present in the installation order)before the given Feature is set to be installed. If any of the Features indicated in thedependsOn property cannot be installed (e.g due to circular dependency, failure to resolve the Feature, etc) the entire dev container creation should fail.
ThedependsOn property must be evaluated recursively. Therefore, if a Feature dependency has its owndependsOn property, that Feature’s dependencies must also be satisfied before the given Feature is installed.
{"name":"My Feature","id":"myFeature","version":"1.0.0","dependsOn":{"foo:1":{"flag":true},"bar:1.2.3":{},"baz@sha256:a4cdc44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"{},}}In the snippet above,myfeature MUST be installed afterfoo,bar, andbaz. If the Features provided via thedependsOn property declare their own dependencies, those must also be satisfied before the Feature is installed.
TheinstallsAfter property indicates a “soft dependency” that influences the installation order of Features that are already queued to be installed. The effective behavior of this property is the same asdependsOn, with the following differences:
installsAfter isnot evaluated recursively.installsAfter only influences the installation order of Features that arealready set to be installed. Any Feature not set to be installed after (1) resolving thedependsOn dependency tree or (2) indicated by the user’sdevcontainer.json should not be added to the installation list.installsAfter cannot provide options, nor are they able to be pinned to a specific version tag or digest. Resolution to the canonical name should still be performed (eg: If the Feature has beenrenamed).{ "name": "My Feature", "id": "myFeature", "version": "1.0.0", "installsAfter": [ "foo", "bar" ]}In the snippet above,myfeature must be installed afterfoo andbarif the Feature is already queued to be installed. Ifsecond andthird are not already queued to be installed, this dependency relationship should be ignored.
TheoverrideFeatureInstallOrder property ofdevcontainer.json is an array of Feature IDs that are to be installed in descending priority order as soon as its dependencies outlined above are installed.
This property may not indicate an installation order that is inconsistent with the resolved dependency graph (seedependency algorithm). If the
overrideFeatureInstallOrderproperty is inconsistent with the dependency graph, the implementing tool should fail the dependency resolution step.
This evaluation is performed by assigning aroundPriority to all nodes that match match the Feature identifier (version omitted) present in the property.
For example, givenn Features in theoverrideFeatureInstallOrder array, the orchestrating tool should assign aroundPriority ofn - idx to each Feature, whereidx is the zero-based index of the Feature in the array.
For example:
overrideFeatureInstallOrder=["foo","bar","baz"]would result in the followingroundPriority assignments:
constroundPriority={"foo":3,"bar":2,"baz":1}This property must not influence the dependency relationship as defined by the dependency graph (seedependency graph) and shall only be evaulated at the round-based sorting step (seeround sort). Put another way, this property cannot “pull forward” a Feature until all of its dependencies (both soft and hard) have been installed. After a Feature’s dependencies have been installed in other rounds, this property should “pull forward” each Feature as early as possible (given the order of identifiers in the array).
Similar toinstallsAfter, this property’s members may not provide options, nor are they able to be pinned to a specific version tag or digest.
If a Feature is indicated inoverrideFeatureInstallOrder but not a member of the dependency graph (it is not queued to be installed), the orchestrating tool may fail the dependency resolution step.
Definitions
Definition: Feature Equality
This specification defines two Features as equal if both Features point to the same exact contents and are executed with > the same options.
For Features published to an OCI registry, two Feature are identical if their manifest digests are equal, and the > options executed against the Feature are equal (compared value by value). Identical manifest digests implies that the tgz contents of the Feature and its entire
devcontainer-feature.jsonare identical. If any of these conditions are not met, the Features are considered not equal.For Features fetched by HTTPS URI, two Features are identical if the contents of the tgz are identical (hash to the > same value), and the options executed against the Feature are equal (compared value by value). If any of these conditions are not met, the Features are considered not equal.
For local Features, each Feature is considered unique and not equal to any other local Feature.
Definition: Round Stable Sort
To prevent non-deterministic behavior, the algorithm will sort eachround according to the following rules:
- Compare and sort each Feature lexiographically by their fully qualified resource name (For OCI-published Features, that means the ID without version or digest.). If the comparison is equal:
- Compare and sort each Feature from oldest to newest tag (
latestbeing the “most new”). If the comparision is equal:- Compare and sort each Feature by their options by:
- Greatest number of user-defined options (note omitting an option will default that value to the Feature’s default value and is not considered a user-defined option). If the comparison is equal:
- Sort the provided option keys lexicographically. If the comparison is equal:
- Sort the provided option values lexicographically. If the comparision is equal:
- Sort Features by their canonical name (For OCI-published Features, the Feature ID resolved to the digest hash).
If there is no difference based on these comparator rules, the Features are considered equal.
Dependency installation order algorithm
An implementing tool is responsible for calculating the Feature installation order (or providing an error if no valid installation order can be resolved). The set of Features to be installed is the union of user-defined Features (those directly indicated in the user’s
devcontainer.jsonand their dependencies (those indicated by thedependsOnorinstallsAfterproperty, taking into account the user dev container’soverrideFeatureInstallOrderproperty). The implmenting tool will perform the following steps:(1) Build a dependency graph
From the user-defined Features, the orchestrating tool will build a dependency graph. The graph will be built by traversing the
dependsOnandinstallsAfterproperties of each Feature. The metadata for each dependency is then fetched and the node added as an edge to to the dependent Feature. FordependsOndependencies, the dependency will be fed back into the worklist to be recursively resolved.An accumulator is maintained with all uniquely discovered and user-provided Features, each with a reference to its dependencies. If the exact Feature (seeFeature Equality) has already been added to the accumulator, it will not be added again. The accumulator will be fed into (B3) after the Feature tree has been resolved.
The graph may be stored as an adjacency list with two kinds of edges (1)
dependsOnedges or “hard dependencies” and (2)installsAfteredges or “soft dependencies”.(2) Assigning round priority
Each node in the graph has an implicit, default
roundPriorityof 0.To influence installation order globally while still honoring the dependency graph of built in(1),
roundPriorityvalues may be tweaks for each Feature. When each round is calculated in(3), only the Features equal to the maxroundPriorityof that set will be committed (the remaining will be > uncommitted and reevaulated in subsequent rounds).The
roundPriorityis set to a non-zero value in the following instances:(3) Round-based sorting
Perform a sort on the result of(1) in rounds. This sort will rearrange Features, producing a sorted list of Features to install. The sort will be performed as follows:
Start with all the elements from(2) in a
worklistand an empty listinstallationOrder. While theworklistis not empty, iterate through each element in theworklistand check if all its dependencies (if any) are already members ofinstallationOrder. If the check is true, add it to an intermediate listroundIf not, skip it. Equality is determined inFeature Equality.Then for each intermediate
roundlist, commit toinstallationOrderonly those nodes who share the maximumroundPriority. Return all nodes inroundwith a strictly lowerroundPriorityto theworklistto be reprocessed in subsequent iterations. If there are multiple nodes with the sameroundPriority, commit them toinstallationOrderwith a final sort according toRound Stable Sort.Repeat for as many rounds as necessary until
worklistis empty. If there is ever a round where no elements are added toinstallationOrder, the algorithm should terminate and return an error. This indicates a circular dependency or other fatal error in the dependency graph. Implementations should attempt to provide the user with information about the error and possible mitigation strategies.Notes
From an implementation point of view,
installsAfternodes may be added as a separate set of directed edges, just asdependsOnnodes are added as directed edges (see(1)). Before round-based installation and sorting(3), an orchestrating tool should remove allinstallsAfterdirected edges that do not correspond with a Feature in theworklistthat is set to be installed. In each round, a Feature can then be installed if all its requirements (bothdependsOnandinstallsAfterdependencies) have been fulfilled in previous rounds.An implemention should fail the dependency resolution step if the evaluation of the
installsAfterproperty results in an inconsistent state (eg: a circular dependency).
A Feature’soptions - specified as the value of a single Feature key/value pair in the user’sdevcontainer.json - are passed to the Feature as environment variables.
A supporting tool will parse theoptions object provided by the user. If a value is provided for a Feature, it will be emitted to a file nameddevcontainer-features.env following the format<OPTION_NAME>=<value>.
To ensure a option that is valid as an environment variable, the follow substitutions are performed:
(str:string)=>str.replace(/[^\w_]/g,'_').replace(/^[\d_]+/g,'_').toUpperCase();This file is sourced at build-time for the featureinstall.sh entrypoint script to handle.
Any options defined by a feature’sdevcontainer-feature.json that are omitted in the user’sdevcontainer.json will be implicitly exported as its default value.
Suppose apython Feature has the followingoptions parameters declared in thedevcontainer-feature.json file:
// ..."options":{"version":{"type":"string","enum":["latest","3.10","3.9","3.8","3.7","3.6"],"default":"latest","description":"Select a Python version to install."},"pip":{"type":"boolean","default":true,"description":"Installs pip"},"optimize":{"type":"boolean","default":true,"description":"Optimize python installation"}}The user’sdevcontainer.json declared the python Feature like so:
"features":{"ghcr.io/devcontainers/features/python:1":{"version":"3.10","pip":false}}The emitted environment variables will be:
VERSION="3.10"PIP="false"OPTIMIZE="true"These will be sourced and visible to theinstall.sh entrypoint script. The followinginstall.sh…
#!/usr/bin/env bashecho"Version is$VERSION"echo"Pip?$PIP"echo"Optimize?$OPTIMIZE"… outputs the following:
Version is 3.10Pip? falseOptimize? trueid property in thedevcontainer-feature.json properties to reflect the newid. Other properties (name,documentationUrl, etc.) can optionally be updated during this step.legacyIds property to the Feature, including the previously usedid.devcontainer features publish command, or equivalent tool that implements theFeatures distribution specification.Let’s say we currently have adocker-from-docker Feature 👇
Currentdevcontainer-feature.json :
{"id":"docker-from-docker","version":"2.0.1","name":"Docker (Docker-from-Docker)","documentationURL":"https://github.com/devcontainers/features/tree/main/src/docker-from-docker",....}We’d want to rename this Feature todocker-outside-of-docker. The source code folder of the Feature will be updated todocker-outside-of-docker and the updateddevcontainer-feature.json will look like 👇
{"id":"docker-outside-of-docker","version":"2.0.2","name":"Docker (Docker-outside-of-Docker)","documentationURL":"https://github.com/devcontainers/features/tree/main/src/docker-outside-of-docker","legacyIds":["docker-from-docker"]....}Note - The semantic version of the Feature defined by theversion property should becontinued and should not be restarted at1.0.0.
There are several things to keep in mind for an application that implements Features:
installsAfter property used by Feature authors. It can be overridden by users if necessary with theoverrideFeatureInstallOrder indevcontainer.json.privileged,init are included if just 1 feature requires them.capAdd,securityOp are concatenated.containerEnv is added before the feature is executed asENV commands in the Dockerfile.