Inside your positron-dev-demo folder, create a new subfolder named .devcontainer. Inside .devcontainer, create a file named devcontainer.json. This file is the blueprint for your environment.

Copy and paste the following into your devcontainer.json file:

{
  "name": "Python 3.11 Data Science",
  // Use a pre-built image to speed up creation.
  "image": "mcr.microsoft.com/devcontainers/python:3.11-bullseye",

  // Features are pre-packaged scripts to add tools. Let's add Git.
  "features": {
    "ghcr.io/devcontainers/features/git:1": {}
  },

  // Forward a port, e.g., if you were running a Streamlit or Flask app.
  "forwardPorts": [8501],

  // Settings and extensions for Positron inside the container.
  "customizations": {
    "positron": {
      "settings": {
        "python.defaultInterpreterPath": "/usr/local/bin/python"
      },
      "extensions": [
        "ms-python.python",
        "ms-toolsai.jupyter"
      ]
    }
  },

  // Run a command after the container is created. Let's install some libraries.
  "postCreateCommand": "pip install pandas numpy scikit-learn"
}

What's happening here?

• name: A human-readable name for your container.
• image: We're telling it to use Microsoft's pre-built Python 3.11 container. This saves a lot of time.
• features: We're easily adding Git to our environment.
• customizations: This is the magic for Positron. We're telling it which extensions to automatically install (Python and Jupyter) and setting a default interpreter.
• postCreateCommand: After the container is built, this command runs. We're using it to install our favorite data science libraries.

Step 2: Launching the Dev Container in Positron

Now for the easy part. Open the positron-dev-demo folder in Positron.

1. Positron will automatically detect the .devcontainer/devcontainer.json file.
2. A small dialog will pop up in the bottom-right corner, asking if you want to "Reopen in Container". Click it.
3. (Alternatively, click the green icon >< in the bottom-left corner of the status bar and select "Reopen in Container".)

The first time you do this, Docker will download the image, which might take a few minutes. Subsequent launches will be much faster. You'll see logs in Positron's terminal as it sets everything up, including running our postCreateCommand.

Step 3: You're In! Now What?

Once it's finished, your Positron window will reload. It looks the same, but it's now connected to your Dev Container. How can you tell?

• The green icon in the bottom-left now says "Dev Container: Python 3.11 Data Science".
• Open the integrated terminal (Ctrl+` or View > Terminal).

In the terminal, try these commands:

# Check the OS (it's Debian Bullseye, not your host OS!)
cat /etc/os-release

# Check the Python version
python --version

# Check for our installed libraries
pip show pandas

Everything is exactly as we defined it! Your project files in positron-dev-demo are mounted directly into the container. Create a new file, `test.py`, and any changes you save are happening on your local disk, but the code is being run and interpreted by the tools inside the container.

Level Up: Pro-Tips for a Smoother Workflow

You've got the basics down. Here are a few tips to make your experience even better.

Managing Secrets and Credentials

Never commit API keys or secrets to your devcontainer.json. The best practice is to mount a local .env file into the container. Add this to your devcontainer.json:

"mounts": [
  "source=${localEnv:HOME}/.secrets/.my_project_env,target=/workspace/.env,type=bind,consistency=cached"
]

This mounts a secret file from your home directory into the project workspace inside the container.

Optimizing Build Times with a Dockerfile

For more complex setups, you might need a custom Dockerfile to install system dependencies (like database clients or geospatial libraries). To keep builds fast, install your OS-level dependencies in the Dockerfile and your project-level dependencies (like Python/Node packages) using postCreateCommand. This leverages Docker's layer caching effectively.

In your .devcontainer folder, create a Dockerfile and update your devcontainer.json to use it:

// In devcontainer.json
"build": {
  "dockerfile": "Dockerfile"
}

Sharing Git Credentials

To avoid logging into Git every time you open your container, you can share your local Git configuration. The easiest way is to use the Git feature, which often handles this for you. If you need more control, you can mount your .gitconfig directly.

Is It Worth It? The Final Verdict

Setting up your first Dev Container takes a little bit of upfront effort. You have to write a configuration file instead of just `pip install`-ing things randomly. But the payoff is enormous.

You're trading 15 minutes of initial configuration for weeks of saved time debugging environment issues, simplifying team onboarding, and gaining the confidence that your code will run anywhere. The combination of Positron's clean, fast interface and the power of Dev Containers creates a development experience that is reproducible, portable, and just plain pleasant to use.

So, the next time you start a new project, give this workflow a try. Say goodbye to "it works on my machine" and hello to a new era of stress-free, consistent development.