Fix VS Code Python warnings in Docker Compose projects

Overview

When editing Python inside a Docker Compose project, VS Code often shows warnings such as:

• Import "X" could not be resolved
• Module not found or type-checking errors

These usually happen because VS Code (and Pylance) are running on your host, but your Python dependencies live inside a container. The fix is to develop inside the container so the Python extension uses the container’s interpreter and site-packages.

Root cause

• Host VS Code uses a host Python interpreter by default.
• Dependencies are installed in the Compose service container, not on the host.
• Pylance and linters can’t see packages inside the container unless VS Code is attached to that container.

Minimal working example

This example shows a Compose-based dev setup where VS Code opens the folder in the container and Pylance stops showing unresolved-import warnings.

Directory layout:

• docker-compose.yml
• .devcontainer/devcontainer.json
• requirements.txt
• app/main.py

docker-compose.yml:

version: "3.8"
services:
  app:
    image: mcr.microsoft.com/devcontainers/python:3.12
    volumes:
      - .:/workspace:cached
      - pip-cache:/root/.cache/pip
    working_dir: /workspace
    command: sleep infinity
volumes:
  pip-cache:

.devcontainer/devcontainer.json:

{
  "name": "py-compose",
  "dockerComposeFile": "../docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspace",
  "overrideCommand": false,
  "postCreateCommand": "python -m pip install -U pip && pip install -r requirements.txt",
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-python.python",
        "ms-python.vscode-pylance"
      ],
      "settings": {
        "python.defaultInterpreterPath": "/usr/local/bin/python",
        "python.analysis.typeCheckingMode": "basic"
      }
    }
  }
}

requirements.txt:

requests==2.32.3

app/main.py:

import requests

def ping() -> None:
    r = requests.get("https://example.com", timeout=1)
    print(r.status_code)

if __name__ == "__main__":
    ping()

Optional: .vscode/launch.json (debug current file inside container):

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Current File (Integrated Terminal)",
      "type": "python",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "justMyCode": true
    }
  ]
}

Quickstart

1. Install required VS Code extensions

• Dev Containers
• Python
• Docker (optional but useful)

1. Create the files above

• Use the provided docker-compose.yml, devcontainer.json, requirements.txt, and app/main.py.

1. Reopen the folder in the container

• In VS Code, press F1 and run: Dev Containers: Reopen in Container.
• VS Code builds/starts the Compose service, mounts your workspace, and runs postCreateCommand to install dependencies.

1. Verify the interpreter

• In the status bar, the Python interpreter should point to /usr/local/bin/python (inside container).
• Open app/main.py. The requests import should resolve without warnings.

1. Run and debug

• Run the script with the Run button or the debug configuration.
• The code executes inside the container using the installed dependencies.

1. Add your tools

• Install pytest, flake8, black, mypy, etc., by adding them to requirements.txt.
• VS Code will use those tools inside the container.

Why this works

• VS Code attaches to the Compose service and runs language features (Pylance, testing, linting) in the container context.
• The interpreter and site-packages are the same ones your application uses at runtime.

Common pitfalls and fixes

• VS Code didn’t reopen in container

  • Symptoms: unresolved imports persist.
  • Fix: use Dev Containers: Reopen in Container. Confirm the green “Dev Container” indicator in the status bar.

• Wrong service name

  • devcontainer.json "service" must match the Compose service (app in the example).

• Workspace path mismatch

  • workspaceFolder must match the Compose mount path (/workspace). If you change one, change the other.

• Container exits immediately

  • Ensure overrideCommand is false and the service runs a long-lived command (sleep infinity) during development.

• Dependencies not installed

  • Check postCreateCommand ran successfully. Use Dev Containers: Rebuild Container after editing requirements.txt to reinstall.

• Host virtualenv confusion

  • Don’t select a host venv as interpreter for a containerized workspace. Use the container Python interpreter.

• Windows/macOS performance

  • Prefer storing the project in WSL2 (Windows) or local filesystem (macOS). Use :cached on volumes to reduce sync overhead.

Performance notes

• Use a prebuilt dev image

  • mcr.microsoft.com/devcontainers/python:3.12 avoids building from scratch.

• Cache pip downloads

  • The pip-cache volume in docker-compose.yml speeds up installs across rebuilds.

• Pin versions

  • Pin Python base image and dependency versions to improve repeatability and reduce rebuild churn.

• Keep containers warm

  • Avoid stopping containers during active development; Dev Containers will reconnect faster to a running service.

• Minimal services

  • During editing, start only the service(s) you need for IntelliSense and tests to keep resource usage low.

Alternatives (when you can’t use Dev Containers)

• Create a host-side virtualenv and pip install -r requirements.txt for editor features only, while still running the app in containers. This keeps IntelliSense accurate, but risks drift versus the container environment. Prefer the Dev Containers approach when possible.

Tiny FAQ

• The unresolved-import warning didn’t go away. What now?

  • Ensure the folder is opened in the container, the interpreter shows a container path, and requirements installed without errors.

• Can I debug under Compose?

  • Yes. Use the Python debug configuration; it runs inside the container when the folder is reopened there.

• Do I need the Docker extension?

  • Not strictly. The Dev Containers and Python extensions are sufficient. Docker extension helps manage containers but isn’t required.

• How do I run tests?

  • Install pytest in requirements.txt. VS Code’s Testing panel will discover and run tests inside the container.

• Can I use a custom Dockerfile?

  • Yes. Reference a build section in docker-compose.yml and point devcontainer.json at that Compose file and service.