# Tutorial: Getting Started with Dev Containers

In this tutorial, you create a Dev Container configuration for a local project, build the container, and open the project inside it. At the end, you have a running container and an IDE window connected to it.

## Before you start

* [Docker](https://docs.docker.com/install/) is installed on your machine and the Docker daemon is running. IntelliJ IDEA builds the container through Docker, so the build fails if the daemon is stopped.

* The [Docker plugin](docker.html) is installed and enabled.

* You have a local project open in IntelliJ IDEA.

For the complete list of requirements, including remote Dev Containers, refer to [Prerequisites](prerequisites-for-dev-containers.html).

## Step 1. Prepare a project

Since the `devcontainer.json` is a necessary configuration file for building Dev Containers, it should be present in the project. The file is placed in the `.devcontainer` folder in the project root; there could be some other folder in between, like `.devcontainer/.../.../devcontainer.json`.

There are two options to quickly start creating Dev Containers: create a simple file or use an in-IDE feature to create a configuration file from the template.

Create a simple configuration file:

The minimal requirement for a Dev Container is the image from which it would be built.

Procedure:

1. In the project view, right-click the project name and select, New | File.

2. Add the file name (`devcontainer.json`).

3. Open the file in the editor and add the following code:

```JSON
{
    image: "ubuntu:latest"
}
```

Create a project from a template:

Procedure:

1. In the project view, right-click the project name and select, New | Dev Container Config.

2. In the dialog that opens, IntelliJ IDEA displays a default container configuration. The default template is enough to create a Dev Container, but any other language-specific template could be selected from the Dev Container Template dropdown if necessary.

Click OK to create a relatively simple (but full of comments) `devcontainer.json`:

```JSON
// Default Ubuntu-based DevContainer Template.
// For more customization options, see https://containers.dev/implementors/json_reference
{
    name: "Default",
    image: "ubuntu:latest",

    customizations : {
        // Configure JetBrains IDE-specific properties
        jetbrains : {
            backend : "IntelliJ",
            settings : {
                // IDE settings can be added via “Show context actions”|“Add currently modified settings from IDE”.
                // A complete list of supported settings is also available through auto-completion
            },
            plugins: [
                // A set of plugin IDs.
                // Plugin ID can be found on the corresponding plugin’s page at https://plugins.jetbrains.com.
            ]
        }
    },
    features: {
        "ghcr.io/devcontainers/features/git" : {},
        // Add additional features to your project using auto-completion.
    },
    // Comment out to connect as the root user.
    remoteUser: "ubuntu"
}
```

## Step 2. Prepare for a build process

You need to consider several additional details to successfully build a container.

Which Dev Container implementation will be used. For the Remote Development (aka first or old) implementation, ensure that the Open devcontainer projects natively option in Settings | Advanced Settings is disabled; for the native mode (aka second) implementation, enable this option.

When RD implementation is used, it is advised to set up the IDE to provide an extended backend choice: How to select the specific IDE backend version for dev containers.

To use the custom remote development backend (maybe necessary to check problems in not-published IDE builds), see IDE backend is not downloaded correctly when building dev containers.

## Step 3. Start a Dev Container build

Procedure:

1. The easiest option to start a Dev Container build is to do it from the opened `devcontainer.json` file through the gutter icon:

2. After the build starts, the Services view should be opened automatically to display the build process:

3. Depending on the implementation chosen (Remote Development vs native mode), the following flow differs a bit.

When Remote Development is used:

Select the backend version from the list and wait while it and the Client are downloaded:

In some cases, if the Dev Container build and backend deployment process takes more than 10 seconds, the Client will not be opened; instead, the notification with the Connect button will be shown in the IDE. Press the button.

Press the Trust Project button in the following window, and wait while Client opens:

How to understand if it is already a project in the Dev Container opened? By the Backend Status Details widget on the top left.

When native mode is used:

Since there is no backend deployment step, the Dev Container project will be opened in the IDE instantly. If the Open project in option in Settings | Appearance & Behavior | System Settings is set up to Ask, the project will be opened after confirmation.

To understand if the project is opened in a Dev Container that uses a native mode, check the unusual project root path and a widget that displays the Dev Container information on the top left of your editor.

![Dev_Container_widget](https://resources.jetbrains.com.cn/help/img/idea/2026.2/devcontainer_widget.png)