Mastering Odoo Docker Debug VSCode: 7 Powerful Steps to Unlock Seamless Development

Debugging is an indispensable skill for any developer, and when working with Odoo in a containerized Docker environment, setting up an efficient debugging workflow can seem challenging. However, with the right approach, integrating Odoo Docker Debug VSCode can dramatically streamline your development process, allowing you to quickly identify and resolve issues in both custom modules and Odoo’s core source code.

This comprehensive guide will walk you through the entire process, from essential Docker commands to configuring VS Code for seamless debugging, and even managing external Python dependencies. The insights shared here are inspired by practical demonstrations, such as this helpful video: How to Debug Odoo in Docker with VS Code ｜｜ Odoo Development.

Let’s dive in and unlock a more efficient Odoo development experience.

---

Why Odoo Docker Debug VSCode is a Game-Changer

Working with Odoo in Docker offers numerous benefits, including isolation, portability, and consistency across development, staging, and production environments. However, debugging inside a Docker container can often feel like working in a black box. This is where Odoo Docker Debug VSCode integration shines.

By attaching VS Code’s powerful debugger to your running Odoo Docker container, you gain the ability to:

• Step through your code line-by-line: Understand the flow of execution in real-time.
• Inspect variables: See the state of your application at any given point.
• Set breakpoints: Pause execution at specific lines of code, both in your custom modules and Odoo’s core.
• Modify variables on the fly: Test potential fixes without restarting Odoo.
• Improve productivity: Spend less time guessing and more time fixing.

This setup ensures that you’re not just running Odoo in Docker, but truly mastering its development within this modern, containerized architecture.

---

Prerequisites for Your Debugging Journey

Before we delve into the technical steps of setting up Odoo Docker Debug VSCode, ensure you have the following in place:

• Odoo Docker Installation: You should have Odoo already installed and running via Docker and Docker Compose. If you haven’t done this yet, you might want to refer to a previous guide on setting up Odoo with Docker.
• Visual Studio Code (VS Code): Download and install the latest version of VS Code from the official website.
• Docker and Docker Compose: Ensure Docker Desktop (which includes Docker Compose) is installed and running on your system. You can get it from Docker’s official site.
• Python Extension for VS Code: Install the Python extension in VS Code for enhanced Python development and debugging capabilities.

With these tools ready, you’re prepared to integrate debugpy and leverage the full potential of Odoo Docker Debug VSCode.

---

Step 1: Essential Docker Commands for Odoo Development

Interacting with your Odoo Docker containers effectively is the first step towards seamless debugging. Here are some fundamental commands you’ll use regularly:

1. Start Your Odoo Container in Detached Mode:
   To run your Odoo and PostgreSQL containers in the background, keeping your terminal free, use:

   docker compose up -d
   

   The -d flag (detached mode) means the containers will run without displaying their logs directly in your current terminal.

2. View Odoo Logs in Real-time:
   If you need to monitor what Odoo is doing, especially during startup or when an error occurs, use:

   docker compose logs -f
   

   The -f flag (follow) continuously streams the logs to your terminal. Press Ctrl+C to exit the log view.

3. Restart Your Odoo Container:
   After making changes to your docker-compose.yml file, or modifying Odoo’s configuration or Python code (that isn’t hot-reloaded), a restart is often necessary:

   docker compose restart
   

   This command will gracefully restart your odoo service, ensuring all changes are applied.

4. Stop and Remove Your Odoo Containers:
   When you’re done with your development session or want to clean up, you can stop and remove the containers and their associated networks:

   docker compose down
   

   This command is useful for freeing up system resources. Be aware that this removes the containers, so any non-persistent data within them will be lost (though Odoo’s database and custom addons are typically volume-mounted for persistence).

5. Access the Odoo Container’s Terminal (Bash):
   Sometimes, you need to execute commands directly inside your Odoo container, for example, to install a new Python dependency.
   First, find the exact name of your running Odoo container:

   docker ps
   

   Look for a container named something like myproject-odoo-1 or similar. Once you have the container name, use docker exec to get a bash shell:

   docker exec -it <container_name> bash
   

   Replace <container_name> with the actual name you found. The -it flags provide an interactive terminal. This step is crucial for the next section, enabling you to prepare your environment for Odoo Docker Debug VSCode.

---

Step 2: Mastering External Python Dependencies in Odoo Docker

Odoo’s ecosystem relies heavily on Python packages. While the official Odoo Docker images come with many common dependencies, you’ll inevitably encounter situations where a custom module requires an external Python library that isn’t pre-installed. Attempting a simple pip3 install inside the container might lead to permission errors or other issues.

Here’s the robust method to install external Python dependencies:

1. Access the Odoo Container’s Terminal:
   As discussed in Step 1: Essential Docker Commands, use the docker exec command to get a bash shell inside your Odoo container:

   docker exec -it <your_odoo_container_name> bash
   

2. Install the Required Package:
   Due to potential restrictions within the Docker image, a standard pip3 install might fail. To ensure successful installation, particularly for packages hosted on PyPI, use the --trusted-host flag:

   pip3 install --trusted-host pypi.python.org <package_name>
   

   Replace <package_name> with the name of the specific Python library your Odoo module needs (e.g., requests, numpy, openpyxl). This command forces pip to trust the PyPI host, circumventing common SSL certificate issues or proxy problems within container environments. This is a vital step to ensure your Odoo environment is ready for comprehensive Odoo Docker Debug VSCode operations.

3. Exit the Container:
   Once the installation is complete, type exit and press Enter to leave the container’s bash shell and return to your host machine’s terminal.

4. Restart the Odoo Container:
   To ensure Odoo recognizes and utilizes the newly installed dependency, restart your service:

   docker compose restart
   

   This ensures that the Odoo application reloads and incorporates the new Python module into its environment.

---

Step 3: Unleashing VS Code for Odoo Docker Debugging

Now for the core of our tutorial: setting up VS Code to debug Odoo running in Docker. This involves modifying your Docker Compose setup, installing a Python debugger, and configuring VS Code’s launch settings.

3.1. Modify docker-compose.yml: Expose Debug Port and Override Command

The first crucial step is to prepare your Docker container for remote debugging. This involves exposing a specific port for the debugger and overriding Odoo’s default startup command to include the debugpy module.

Open your docker-compose.yml file and make the following adjustments to your odoo service:

version: '3.1'
services:
  odoo:
    image: odoo:16.0 # Replace with your Odoo version, e.g., odoo:17.0
    # ... other configurations like environment, depends_on ...
    ports:
      - "8069:8069"       # Odoo's standard web port
      - "5678:5678"       # **Expose the debug port for VS Code**
    volumes:
      - odoo-web-data:/var/lib/odoo
      - ./config:/etc/odoo
      - ./addons:/mnt/extra-addons # Your custom addons folder
      # You might also want to mount Odoo source code if you plan to modify it often:
      # - /path/to/your/local/odoo/source:/usr/lib/python3/dist-packages/odoo
    command: >
      python3 -m debugpy
      --listen 0.0.0.0:5678
      --wait-for-client
      /usr/bin/odoo
      -c /etc/odoo/odoo.conf
      --addons-path=/mnt/extra-addons,/usr/lib/python3/dist-packages/odoo/addons
      --stop-after-init
      --log-level=debug
      --dev=all

Explanation of the changes:

• ports: - "5678:5678": This line is paramount. It maps port 5678 from your host machine to port 5678 inside the Odoo container. This is the port debugpy will listen on, allowing VS Code to connect.
• command: > python3 -m debugpy ...: This overrides the default command used to start Odoo within the container.
  • python3 -m debugpy: Invokes the debugpy module to start the Python debugger.
  • --listen 0.0.0.0:5678: Tells debugpy to listen for incoming connections on all network interfaces (0.0.0.0) on port 5678.
  • --wait-for-client: This is a critical flag. It instructs debugpy to pause the execution of Odoo until a debugger client (VS Code) connects. This ensures you have time to attach your debugger before Odoo fully initializes, allowing you to debug even early startup code.
  • /usr/bin/odoo -c /etc/odoo/odoo.conf --addons-path=... --stop-after-init --log-level=debug --dev=all: These are the standard Odoo startup arguments.
    • -c /etc/odoo/odoo.conf: Specifies the Odoo configuration file.
    • --addons-path: Defines where Odoo should look for modules. Make sure to include both your custom addons path (e.g., /mnt/extra-addons) and Odoo’s default addons path (/usr/lib/python3/dist-packages/odoo/addons).
    • --stop-after-init: Useful for initial setup or debugging startup issues, as Odoo will stop after loading modules. You might remove this after initial debugging.
    • --log-level=debug: Sets the verbosity of Odoo’s logs, which can be helpful during debugging.
    • --dev=all: Enables Odoo’s developer mode features.

3.2. Install debugpy in the Odoo Container

Even though we’re instructing Odoo to start with debugpy, the debugpy package itself needs to be present in the container.

1. Access the Odoo Container’s Terminal:
   Use docker exec -it <your_odoo_container_name> bash as you learned in Step 1.

2. Install debugpy:
   Run the following command to install the debugpy package:

   pip3 install debugpy
   

   This installs the necessary debugger components that the command override in your docker-compose.yml will use.

3. Exit the Container:
   Type exit to return to your host terminal.

3.3. Configure launch.json in VS Code

This is where you tell VS Code how to connect to the debugpy server running inside your Odoo Docker container.

1. Open VS Code and Go to Run and Debug:
   In VS Code, navigate to the “Run and Debug” view (usually accessible via Ctrl+Shift+D or by clicking the bug icon in the sidebar).

2. Create launch.json:
   If you don’t have a launch.json file in your workspace’s .vscode folder, click on the “create a launch.json file” link and select “Python File” or “Python: Remote Attach”.

3. Paste the Configuration:
   Replace the contents of the generated launch.json with the following. Crucially, you MUST adjust the localRoot paths in the pathMappings section to match the actual locations of your Odoo source code and custom addons on your local machine.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Attach to Odoo Docker",
            "type": "debugpy",
            "request": "attach",
            "connect": {
                "host": "localhost",
                "port": 5678
            },
            "pathMappings": [
                {
                    "localRoot": "${workspaceFolder}/odoo-source-16", // **Local path to your Odoo source code**
                    "remoteRoot": "/usr/lib/python3/dist-packages/odoo" // Odoo's installation path inside Docker
                },
                {
                    "localRoot": "${workspaceFolder}/custom_addons", // **Local path to your custom addons folder**
                    "remoteRoot": "/mnt/extra-addons" // Your custom addons path inside Docker
                }
            ],
            "justMyCode": false // Essential for debugging Odoo's core modules
        }
    ]
}

Understanding launch.json:

• name: A friendly name for your debug configuration in VS Code.
• type: Specifies the debugger backend (debugpy for Python).
• request: Set to attach because VS Code will attach to an already running debugger process.
• connect: Defines how VS Code connects to debugpy. localhost:5678 corresponds to the port we exposed in docker-compose.yml.

• pathMappings: This is the most critical part for successful Odoo Docker Debug VSCode integration. It tells VS Code how to translate file paths between your local machine (where VS Code is running) and the remote Docker container (where Odoo is running).

  • localRoot: The absolute path to your Odoo source code or custom addons directory on your host machine.
  • remoteRoot: The corresponding absolute path to that code inside the Docker container.
  • For Odoo’s core source, you’ll need to download the Odoo repository from GitHub (or your specific version) to your local machine and point localRoot to it. The remoteRoot for Odoo’s core is typically /usr/lib/python3/dist-packages/odoo in official Docker images.
  • For custom addons, localRoot points to your local custom addons folder, and remoteRoot points to the folder mounted inside the container (e.g., /mnt/extra-addons).
• justMyCode: false: This setting is vital for debugging Odoo. If set to true, the debugger would skip stepping into Odoo’s core files or any libraries that are not considered “your code.” Setting it to false allows you to debug all Python code, including Odoo’s internal logic.

3.4. Start the Odoo Container

With your docker-compose.yml updated and debugpy installed, start your Odoo container. Remember the --wait-for-client flag means Odoo will pause, waiting for VS Code to connect.

docker compose up -d --build

The --build flag ensures that if you’ve made changes to your docker-compose.yml (like the command override), the service is rebuilt or updated correctly. You might also use docker compose restart if the container is already running and you just changed the command.

You might notice in your docker compose logs -f that Odoo starts but then seems to hang, indicating it’s waiting for the debugger.

3.5. Initiate Debugging in VS Code

Now, connect VS Code to your waiting Odoo container:

1. Set Breakpoints: Open any Odoo Python file (from your custom modules or the Odoo source code downloaded locally) in VS Code and click in the gutter next to a line number to set a breakpoint.
2. Select Debug Configuration: In the “Run and Debug” view in VS Code, ensure “Attach to Odoo Docker” is selected in the dropdown menu at the top.
3. Start Debugging: Click the green “Start Debugging” play button.

VS Code will now attempt to connect to your Odoo Docker container on localhost:5678. Once connected, Odoo will resume its startup process, and if it hits any of your breakpoints during initialization, it will pause there.

3.6. Trigger and Interact with Breakpoints

Once Odoo is running and your debugger is attached:

1. Trigger the Action: Perform the action in your Odoo web interface that corresponds to the code where you’ve set a breakpoint. For example, if you set a breakpoint in a method called when saving a record, go to Odoo and save that type of record.
2. Debug in VS Code: VS Code will pause execution at your breakpoint. You can now use the debug controls (Step Over, Step Into, Step Out, Continue) to navigate your code. The “Variables” panel will show you the current state of variables, and the “Debug Console” allows you to execute Python expressions and inspect objects in the current context (e.g., self.name to see a record’s name).

---

Step 4: Debugging Odoo Source Code vs. Custom Modules

The beauty of the pathMappings configuration in launch.json is that it allows you to debug both your custom modules and Odoo’s core source code with the same setup.

• Custom Modules: When you set a breakpoint in my_custom_module/models/my_model.py (which is mapped from your local custom_addons folder to /mnt/extra-addons in Docker), VS Code will stop there.
• Odoo Core: Similarly, if you set a breakpoint in odoo/addons/account/models/account_move.py (from your locally downloaded Odoo source, mapped to /usr/lib/python3/dist-packages/odoo), VS Code will also stop there, allowing you to examine Odoo’s internal logic.

The justMyCode: false setting ensures that the debugger doesn’t differentiate between “your” code and Odoo’s code, giving you full visibility into the entire application stack when using Odoo Docker Debug VSCode.

---

Step 5: Advanced Tip – Running Multiple Odoo Instances

It’s common for developers to work on projects for different Odoo versions (e.g., Odoo 16 and Odoo 17) or entirely separate instances. Running multiple Odoo Docker instances concurrently is straightforward:

1. Create Separate Directories: For each Odoo instance, create a dedicated project directory (e.g., odoo-project-16, odoo-project-17).

2. Copy Docker Setup: Inside each directory, set up your docker-compose.yml and associated configuration files just as you would for a single instance.

3. Adjust Port Mappings: This is the critical part to avoid conflicts. In each docker-compose.yml, ensure the host port mappings are unique. For example:

   • odoo-project-16: 8069:8069, 5678:5678
   • odoo-project-17: 8070:8069, 5679:5678 (Host port 8070 maps to container’s 8069, host 5679 maps to container’s 5678)

4. Run Independently: Navigate to each project directory and run docker compose up -d separately.

This allows you to have multiple, isolated Odoo development environments running simultaneously, each with its own Odoo Docker Debug VSCode setup tailored to its specific version or project.

---

Troubleshooting Common Odoo Docker Debug VSCode Issues

Even with a detailed guide, you might encounter issues. Here are some common problems and their solutions:

• Debugger Not Connecting / Odoo Hanging:

  • Check Port Mapping: Ensure 5678:5678 is correctly configured in your docker-compose.yml.
  • debugpy Installation: Verify debugpy is installed inside the Odoo container (pip3 install debugpy).
  • --wait-for-client: Confirm this flag is present in your docker-compose.yml command. If it’s missing, Odoo might start and finish before VS Code has a chance to attach.
  • Restart Container: Always restart your Docker container after docker-compose.yml or debugpy installation changes.

• Breakpoints Not Hitting:

  • Path Mappings: This is the most frequent culprit. Double-check your localRoot and remoteRoot paths in launch.json. They must be exact, including case sensitivity. If you’re having trouble, try simplifying them to just one custom addon for testing.
  • justMyCode: false: Ensure this is set correctly in launch.json if you’re trying to debug Odoo’s core modules.
  • Code Execution: Is the code path with the breakpoint actually being executed by Odoo? Sometimes, an action doesn’t trigger the specific function you’re expecting.

• Permission Errors During pip3 install:

  • Use the --trusted-host pypi.python.org flag as described in Step 2.
  • Ensure you are using pip3 (for Python 3), not just pip.

• Odoo command Override Errors:

  • Syntax: Pay close attention to the YAML syntax for the command block, especially the > for multi-line commands. Incorrect indentation or missing quotes can cause issues.
  • Path Correctness: Verify that /usr/bin/odoo, /etc/odoo/odoo.conf, and your --addons-path values are correct for your Odoo Docker image.

By carefully reviewing these points, you can often quickly resolve any hiccups in your Odoo Docker Debug VSCode setup.

---

Conclusion: Elevate Your Odoo Development Workflow

Integrating Odoo Docker Debug VSCode transforms a potentially cumbersome process into a powerful and efficient development experience. By following these 7 detailed steps—from mastering essential Docker commands and handling Python dependencies to configuring VS Code for precise debugging—you gain unparalleled insight into your Odoo application’s behavior.

This setup not only accelerates problem-solving but also deepens your understanding of Odoo’s internal workings, empowering you to build more robust and reliable solutions. Embrace this modern approach to Odoo development and unlock a new level of productivity.

If you found this guide helpful, please share it with your fellow Odoo developers! Your feedback and engagement help us create more valuable content.