How to Set a Custom Docker Container Name in a Dev Container

If you've ever used Dev Containers in VS Code, you've probably noticed that your container ends up with a random generated name like upbeat_heyrovsky or zealous_bookworm — even after setting the "name" field in your devcontainer.json.

That's because "name" is just the display name in VS Code. It has nothing to do with the actual Docker container name.

Before — random generated name:

The Problem

When your devcontainer.json uses a single image (no Docker Compose), there's no obvious way to control the container name:

{
  "name": "my_project", // ← this is just a VS Code label
  "image": "mcr.microsoft.com/devcontainers/typescript-node:3-24"
}

VS Code will still spin up a container with a random Docker name. Tools like OrbStack or Docker Desktop will show something completely unrelated to your project.

The Fix

Use runArgs to pass Docker run arguments directly:

{
  "name": "my_project",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:3-24",
  "runArgs": ["--name", "my_project"]
}

That's it. runArgs lets you pass any valid docker run flag — and --name sets the container name exactly as you'd expect.

Result

Your container will now show up as my_project in Docker Desktop, OrbStack, or any other Docker UI — no more random adjective-noun combos.

After — custom name with runArgs:

What If You're Using a Docker Compose File?

If your devcontainer.json uses dockerComposeFile instead of a single image, the runArgs approach won't apply. In that case, create a .env file next to your docker-compose.yml and set:

COMPOSE_PROJECT_NAME=my_project

Docker Compose automatically picks this up and uses it as the project name — so your containers will show as my_project-db-1, my_project-workspaces-1, etc. instead of the folder name.

Your devcontainer.json stays untouched:

{
  "name": "my_project",
  "dockerComposeFile": "docker-compose.yml",
  "service": "workspaces"
}

Quick Summary

Setup	Solution
Single image in devcontainer.json	"runArgs": ["--name", "my_project"]
dockerComposeFile in devcontainer.json	.env with COMPOSE_PROJECT_NAME=my_project

And just to save you the time — "dockerComposeProjectName" is not a valid devcontainer.json property, VS Code will throw a validation error if you try it.

---

Small tip, but one of those things that's weirdly hard to find in the docs.