How to debug inside a Docker container with VSCode?
Jul 10, 2025 pm 12:40 PMThe key to debugging code with VSCode in a Docker container is to configure the development environment and connection methods. 1. Prepare a mirror with development tools, install necessary dependencies such as debugpy or node, and use the official devcontainers image to simplify configuration; 2. Mount the source code and enable the Remote-Containers plug-in, create .devcontainer folders and configuration files, and realize in-container development; 3. Configure the debugger, add debug settings for the corresponding language in launch.json, and enable the listening port in the code; 4. Solve common problems, such as exposing the debug port, ensuring the host is 0.0.0.0, and automatically initialize the command with postCreateCommand to ensure smooth debugging process.
Using VSCode to debug code in a Docker container is actually not complicated. The key is to "moving" the development environment into the container, and at the same time, allowing VSCode to be connected normally. As long as the configuration is properly, the debugging experience is almost as smooth as the local one.

1. Prepare a mirror with development tools
To debug in a container, you must first ensure that there are necessary development dependencies in the container. For example, if you use Python, you need to install python3
, pip
, debugpy
; if you use Node.js, you need to install node
and npm
. If you are building on official images, you can add these to your Dockerfile:

- Install commonly used debugging dependencies (taking Python as an example):
RUN pip install debugpy
You can also directly use basic images that already include the development environment, such as mcr.microsoft.com/vscode/devcontainers/base
series images provided by Microsoft, eliminating manual configuration steps.
2. Mount the source code and enable SSH or Remote-Containers plug-in
VSCode The most common way to access the code in a container is through the Remote - Containers plugin. This plugin allows you to put the entire development environment in a container, and the editor itself runs on the host.

The operation steps are roughly as follows:
- Install Remote for VSCode - Containers plugin
- Create a
.devcontainer
folder in the project root directory - Configure the
devcontainer.json
file to specify the image, port mapping, mount volume, etc. - Click the green icon in the lower right corner and select "Reopen in Container"
In this way, VSCode will automatically start or build the container and mount the current project directory. You can open the terminal and debug the code like locally.
3. Configure the debugger (launch.json)
After entering the container, the next step is to set up the debugger. Taking Python as an example, you need to add a configuration item in .vscode/launch.json
:
{ "version": "0.2.0", "configurations": [ { "name": "Python: Remote debug container", "type": "python", "request": "launch", "program": "${workspaceFolder}/your_script.py", "console": "integratedTerminal", "justMyCode": true, "host": "localhost", "port": 5678 } ] }
Then insert the debug listener in the code:
import debugpy debugpy.listen(('0.0.0.0', 5678)) debugpy.wait_for_client()
After starting debugging, VSCode can be connected to the debugging service in the container.
If it is Node.js, it is similar. Just change the launch.json type to node
and specify the entry file.
4. FAQs and Tips
Sometimes you will find that the debugger cannot be connected, maybe because:
- The container does not expose the corresponding debug port (such as 5678). Remember to add port mapping when
devcontainer.json
ordocker run
- Your script is not running after the container is started, or the script does not trigger
listen()
, causing the debugger to be unable to connect. - Network isolation problem: Make sure the host is
0.0.0.0
, do not write it as127.0.0.1
, otherwise the external cannot be connected.
Another trick is that you can use the postCreateCommand
field of devcontainer.json
to automatically execute some initialization commands after the container is created, such as installing dependencies or starting services.
Basically that's it. Although the whole process seems a bit too many, once .devcontainer
and launch.json
are configured, each time you open the project, you can enter the container and debug it with one click, which is very obvious.
The above is the detailed content of How to debug inside a Docker container with VSCode?. For more information, please follow other related articles on the PHP Chinese website!

Hot AI Tools

Undress AI Tool
Undress images for free

Undresser.AI Undress
AI-powered app for creating realistic nude photos

AI Clothes Remover
Online AI tool for removing clothes from photos.

Clothoff.io
AI clothes remover

Video Face Swap
Swap faces in any video effortlessly with our completely free AI face swap tool!

Hot Article

Hot Tools

Notepad++7.3.1
Easy-to-use and free code editor

SublimeText3 Chinese version
Chinese version, very easy to use

Zend Studio 13.0.1
Powerful PHP integrated development environment

Dreamweaver CS6
Visual web development tools

SublimeText3 Mac version
God-level code editing software (SublimeText3)

Hot Topics

There are three ways to change the default terminal in VSCode: setting through a graphical interface, editing settings.json file, and temporary switching. First, open the settings interface and search for "terminalintegratedshell" and select the terminal path of the corresponding system; secondly, advanced users can edit settings.json to add "terminal.integrated.shell.windows" or "terminal.integrated.shell.osx" fields and escape the path correctly; finally, you can enter "Terminal:SelectD through the command panel

When encountering Docker problems, you should first locate the problem, which is problems such as image construction, container operation or network configuration, and then follow the steps to check. 1. Check the container log (dockerlogs or docker-composelogs) to obtain error information; 2. Check the container status (dockerps) and resource usage (dockerstats) to determine whether there is an exception due to insufficient memory or port problems; 3. Enter the inside of the container (dockerexec) to verify the path, permissions and dependencies; 4. Review whether there are configuration errors in the Dockerfile and compose files, such as environment variable spelling or volume mount path problems, and recommend that cleanbuild avoid cache dryness

The main difference between Docker and traditional virtualization lies in the processing and resource usage of the operating system layer. 1. Docker containers share the host OS kernel, which is lighter, faster startup, and more resource efficiency; 2. Each instance of a traditional VM runs a full OS, occupying more space and resources; 3. The container usually starts in a few seconds, and the VM may take several minutes; 4. The container depends on namespace and cgroups to achieve isolation, while the VM obtains stronger isolation through hypervisor simulation hardware; 5. Docker has better portability, ensuring that applications run consistently in different environments, suitable for microservices and cloud environment deployment.

When the "Timedoutwaitingforthedebuggertoattach" issue occurs, it is usually because the connection is not established correctly in the debugging process. 1. Check whether the launch.json configuration is correct, ensure that the request type is launch or attach and there is no spelling error; 2. Confirm whether the debugger is waiting for the debugger to connect, and add debugpy.wait_for_attach() and other mechanisms; 3. Check whether the port is occupied or firewall restricted, and replace the port or close the occupied process if necessary; 4. Confirm that the port mapping and access permissions are configured correctly in a remote or container environment; 5. Update VSCode, plug-in and debug library versions to solve potential

To set debug environment variables in VSCode, you need to use the "environment" array configuration in the launch.json file. The specific steps are as follows: 1. Add "environment" array to the debugging configuration of launch.json, and define variables in key-value pairs, such as API_ENDPOINT and DEBUG_MODE; 2. You can load variables through .env files to improve management efficiency, and use envFile to specify file paths in launch.json; 3. If you need to overwrite the system or terminal variables, you can directly redefine them in launch.json; 4. Note that

To expose Docker container ports, the host needs to access the container service through port mapping. 1. Use the dockerrun-p[host_port]:[container_port] command to run the container, such as dockerrun-p8080:3000my-web-app; 2. Use the EXPOSE instruction to mark the purpose in the Dockerfile, such as EXPOSE3000, but the port will not be automatically published; 3. Configure the ports segment of the yml file in DockerCompose, such as ports:-"8080:3000"; 4. Use dockerps to check whether the port map is generated after running.

There are three main ways to set environment variables in PHP: 1. Global configuration through php.ini; 2. Passed through a web server (such as SetEnv of Apache or fastcgi_param of Nginx); 3. Use putenv() function in PHP scripts. Among them, php.ini is suitable for global and infrequently changing configurations, web server configuration is suitable for scenarios that need to be isolated, and putenv() is suitable for temporary variables. Persistence policies include configuration files (such as php.ini or web server configuration), .env files are loaded with dotenv library, and dynamic injection of variables in CI/CD processes. Security management sensitive information should be avoided hard-coded, and it is recommended to use.en

The key to debugging code with VSCode in Docker containers is to configure the development environment and connection methods. 1. Prepare a mirror with development tools, install necessary dependencies such as debugpy or node, and use the official devcontainers image to simplify configuration; 2. Mount the source code and enable the Remote-Containers plug-in, create .devcontainer folders and configuration files, and realize in-container development; 3. Configure the debugger, add debug settings for the corresponding language in launch.json, and enable the listening port in the code; 4. Solve common problems, such as exposing the debug port, ensuring the host is 0.0.0.0, and use postCreateC
