README.md

pycontainer-build for VS Code

Build OCI container images from Python projects directly in Visual Studio Code — no Docker required.

Features

• 🚀 Build Containers - Build OCI images with a single command
• 🔄 Push to Registry - Push images to GHCR, ACR, Docker Hub
• ⚙️ Configuration - Generate pycontainer.toml configuration
• 📊 Output Channel - View build progress in real-time
• 🐍 Python Native - No Docker daemon needed

Requirements

• Visual Studio Code 1.80.0 or higher
• Python 3.11 or higher
• pycontainer-build (automatically installed if needed)

Installation

From VS Code Marketplace

1. Open VS Code
2. Press Ctrl+Shift+X (Windows/Linux) or Cmd+Shift+X (Mac)
3. Search for "pycontainer-build"
4. Click Install

From VSIX

code --install-extension vscode-pycontainer-0.1.0.vsix

Usage

Build Container

1. Open a Python project with pyproject.toml
2. Open Command Palette (Ctrl+Shift+P or Cmd+Shift+P)
3. Type "pycontainer: Build Container Image"
4. Enter image tag (e.g., myapp:latest)
5. View build progress in the output panel

Build and Push

1. Open Command Palette
2. Type "pycontainer: Build and Push Container Image"
3. Enter image tag (e.g., ghcr.io/user/myapp:v1)
4. Image will be built and pushed to registry

Configure Build

1. Open Command Palette
2. Type "pycontainer: Configure Container Build"
3. A pycontainer.toml file will be created
4. Edit the configuration as needed

Context Menu

Right-click on pyproject.toml in the Explorer:

• Select "Build Container Image"

Configuration

Extension Settings

Configure the extension in VS Code settings:

{
  "pycontainer.pythonPath": "python",
  "pycontainer.defaultTag": "myapp:latest",
  "pycontainer.defaultBaseImage": "python:3.11-slim",
  "pycontainer.autoInstall": true,
  "pycontainer.showOutput": true,
  "pycontainer.verbose": false
}

Project Configuration

Create pycontainer.toml in your project:

[build]
base_image = "python:3.11-slim"
workdir = "/app"
include_deps = true

[build.env]
ENV = "production"
PORT = "8080"

[registry]
url = "ghcr.io/user/myapp"

Commands

Command	Description	Keyboard Shortcut
pycontainer.build	Build container image	-
pycontainer.buildAndPush	Build and push image	-
pycontainer.configure	Create configuration file	-

Examples

Basic FastAPI App

# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

# pyproject.toml
[project]
name = "myapi"
version = "1.0.0"
dependencies = ["fastapi", "uvicorn"]

[project.scripts]
start = "uvicorn main:app --host 0.0.0.0 --port 8000"

Build: Open Command Palette → "Build Container Image" → Enter myapi:latest

Flask App with Configuration

# app.py
from flask import Flask

app = Flask(__name__)

@app.route("/")
def hello():
    return "Hello World!"

# pycontainer.toml
[build]
base_image = "python:3.11-slim"
include_deps = true

[build.env]
FLASK_APP = "app"
FLASK_ENV = "production"

Build: Right-click pyproject.toml → "Build Container Image"

Integration with GitHub Actions

Use the extension locally, then deploy with GitHub Actions:

# .github/workflows/build.yml
name: Build Container

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Build and push
        run: |
          pip install pycontainer-build
          pycontainer build --tag ghcr.io/${{ github.repository }}:latest --push
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Troubleshooting

"pycontainer-build not installed"

The extension will automatically prompt to install it. Or install manually:

pip install pycontainer-build

"No pyproject.toml found"

Ensure your workspace has a pyproject.toml file at the root.

Build fails with "Permission denied"

For registry push, ensure you're authenticated:

# GitHub Container Registry
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

# Azure Container Registry
az acr login --name myregistry

Python path not found

Configure the correct Python path in settings:

{
  "pycontainer.pythonPath": "/usr/bin/python3.11"
}

Development

Building the Extension

cd plugins/vscode-pycontainer
npm install
npm run compile

Packaging

npm run package

This creates vscode-pycontainer-0.1.0.vsix.

Testing

1. Press F5 in VS Code to open Extension Development Host
2. Test commands in the new window

Roadmap

• Interactive configuration wizard
• Build status in status bar
• Quick pick for recent images
• Integration with Docker extension
• Multi-platform build support
• Build history view

Contributing

Contributions welcome! See CONTRIBUTING.md.

License

MIT License - See LICENSE file for details.

Related Projects

• pycontainer-build - Core builder
• poetry-pycontainer - Poetry plugin
• hatch-pycontainer - Hatch plugin

Support

• GitHub Issues
• Documentation