feat(vllm-metal): include python

Signed-off-by: Dorin Geman <dorin.geman@docker.com>

Author: doringeman

Makefile

@@ -144,7 +144,8 @@ docker-run-impl:
 	DEBUG="${DEBUG}" \
 	scripts/docker-run.sh
 
-# vllm-metal (macOS ARM64 only, requires Python 3.12 for wheel compatibility)
+# vllm-metal (macOS ARM64 only)
+# The tarball is self-contained: includes a standalone Python 3.12 + all packages.
 VLLM_METAL_RELEASE ?= v0.1.0-20260126-121650
 VLLM_METAL_INSTALL_DIR := $(HOME)/.docker/model-runner/vllm-metal
 VLLM_METAL_TARBALL := vllm-metal-macos-arm64-$(VLLM_METAL_RELEASE).tar.gz
@@ -169,26 +170,9 @@ vllm-metal-install:
 		exit 1; \
 	fi; \
 	echo "Installing vllm-metal to $(VLLM_METAL_INSTALL_DIR)..."; \
-	PYTHON_BIN=""; \
-	if command -v python3.12 >/dev/null 2>&1; then \
-		PYTHON_BIN="python3.12"; \
-	elif command -v python3 >/dev/null 2>&1; then \
-		version=$$(python3 --version 2>&1 | grep -oE '[0-9]+\.[0-9]+'); \
-		if [ "$$version" = "3.12" ]; then \
-			PYTHON_BIN="python3"; \
-		fi; \
-	fi; \
-	if [ -z "$$PYTHON_BIN" ]; then \
-		echo "Error: Python 3.12 required (vllm-metal wheel is built for cp312)"; \
-		echo "Install with: brew install python@3.12"; \
-		exit 1; \
-	fi; \
-	echo "Using Python 3.12 from $$(which $$PYTHON_BIN)"; \
 	rm -rf "$(VLLM_METAL_INSTALL_DIR)"; \
-	$$PYTHON_BIN -m venv "$(VLLM_METAL_INSTALL_DIR)"; \
-	SITE_PACKAGES="$(VLLM_METAL_INSTALL_DIR)/lib/python3.12/site-packages"; \
-	mkdir -p "$$SITE_PACKAGES"; \
-	tar -xzf "$(VLLM_METAL_TARBALL)" -C "$$SITE_PACKAGES"; \
+	mkdir -p "$(VLLM_METAL_INSTALL_DIR)"; \
+	tar -xzf "$(VLLM_METAL_TARBALL)" -C "$(VLLM_METAL_INSTALL_DIR)"; \
 	echo "$(VLLM_METAL_RELEASE)" > "$$VERSION_FILE"; \
 	echo "vllm-metal $(VLLM_METAL_RELEASE) installed successfully!"
 
@@ -266,10 +250,10 @@ help:
 	@echo "  make run LOCAL_LLAMA=1"
 	@echo "  make docker-run LLAMA_ARGS=\"--verbose --jinja -ngl 999 --threads 4 --ctx-size 2048\""
 	@echo ""
-	@echo "vllm-metal (macOS ARM64 only, requires Python 3.12):"
+	@echo "vllm-metal (macOS ARM64 only):"
 	@echo "  1. Auto-pull from Docker Hub (clean dev installs first: make vllm-metal-clean):"
 	@echo "     make run"
 	@echo "  2. Build and install from tarball:"
 	@echo "     make vllm-metal-build && make vllm-metal-install && make run"
-	@echo "  3. Install from local source (for development):"
+	@echo "  3. Install from local source (for development, requires Python 3.12):"
 	@echo "     make vllm-metal-dev VLLM_METAL_PATH=../vllm-metal && make run"

pkg/inference/backends/vllmmetal/vllmmetal.go

@@ -42,7 +42,7 @@ type vllmMetal struct {
 	modelManager *models.Manager
 	// serverLog is the logger to use for the vllm-metal server process.
 	serverLog logging.Logger
-	// pythonPath is the path to the python3 binary in the venv.
+	// pythonPath is the path to the bundled python3 binary.
 	pythonPath string
 	// customPythonPath is an optional custom path to a python3 binary.
 	customPythonPath string
@@ -127,54 +127,9 @@ func (v *vllmMetal) Install(ctx context.Context, httpClient *http.Client) error
 	return v.verifyInstallation(ctx)
 }
 
-// findSystemPython finds Python 3.12 interpreter on the system.
-// Python 3.12 is required because the vllm-metal wheel is built for cp312.
-func (v *vllmMetal) findSystemPython(ctx context.Context) (string, string, error) {
-	// Try python3.12 first
-	for _, pyCmd := range []string{"python3.12", "python3"} {
-		pythonPath, err := exec.LookPath(pyCmd)
-		if err != nil {
-			continue
-		}
-
-		// Verify version is exactly 3.12
-		out, err := exec.CommandContext(ctx, pythonPath, "--version").Output()
-		if err != nil {
-			continue
-		}
-
-		versionStr := strings.TrimPrefix(strings.TrimSpace(string(out)), "Python ")
-		parts := strings.Split(versionStr, ".")
-		if len(parts) < 2 {
-			continue
-		}
-
-		major, err := strconv.Atoi(parts[0])
-		if err != nil {
-			continue
-		}
-		minor, err := strconv.Atoi(parts[1])
-		if err != nil {
-			continue
-		}
-
-		// Must be exactly Python 3.12 for wheel compatibility
-		if major == 3 && minor == 12 {
-			return pythonPath, "3.12", nil
-		}
-	}
-
-	return "", "", fmt.Errorf("python 3.12 required (vllm-metal wheel is built for cp312); install with: brew install python@3.12")
-}
-
 // downloadAndExtract downloads the vllm-metal image from Docker Hub and extracts it.
+// The image contains a self-contained Python installation with all packages pre-installed.
 func (v *vllmMetal) downloadAndExtract(ctx context.Context, _ *http.Client) error {
-	pythonPath, pyVersion, err := v.findSystemPython(ctx)
-	if err != nil {
-		return err
-	}
-
-	v.log.Infof("Using system Python %s from %s", pyVersion, pythonPath)
 	v.log.Infof("Downloading vllm-metal %s from Docker Hub...", vllmMetalVersion)
 
 	// Create temp directory for download
@@ -196,7 +151,6 @@ func (v *vllmMetal) downloadAndExtract(ctx context.Context, _ *http.Client) erro
 		return fmt.Errorf("failed to extract image: %w", err)
 	}
 
-	v.log.Infof("Creating Python venv at %s...", v.installDir)
 	if err := os.MkdirAll(filepath.Dir(v.installDir), 0755); err != nil {
 		return fmt.Errorf("failed to create parent dir: %w", err)
 	}
@@ -206,18 +160,13 @@ func (v *vllmMetal) downloadAndExtract(ctx context.Context, _ *http.Client) erro
 		return fmt.Errorf("failed to remove existing install dir: %w", err)
 	}
 
-	venvCmd := exec.CommandContext(ctx, pythonPath, "-m", "venv", v.installDir)
-	if out, err := venvCmd.CombinedOutput(); err != nil {
-		return fmt.Errorf("failed to create venv: %w\nOutput: %s", err, string(out))
-	}
-
-	v.log.Infof("Extracting packages...")
-	sitePackagesDir := filepath.Join(v.installDir, "lib", fmt.Sprintf("python%s", pyVersion), "site-packages")
+	v.log.Infof("Extracting self-contained Python environment...")
 
-	// Copy extracted files to site-packages (the image contains /vllm-metal/*)
+	// Copy the extracted self-contained Python installation directly to install dir
+	// (the image contains /vllm-metal/ with bin/, lib/, etc.)
 	vllmMetalDir := filepath.Join(extractDir, "vllm-metal")
-	if err := copyDir(vllmMetalDir, sitePackagesDir); err != nil {
-		return fmt.Errorf("failed to copy to site-packages: %w", err)
+	if err := copyDir(vllmMetalDir, v.installDir); err != nil {
+		return fmt.Errorf("failed to copy to install dir: %w", err)
 	}
 
 	v.log.Infof("vllm-metal %s installed successfully", vllmMetalVersion)

scripts/build-vllm-metal-tarball.sh

@@ -1,22 +1,21 @@
 #!/bin/bash
 # Build script for vllm-metal macOS tarball distribution
-# Creates a tarball containing Python site-packages for vllm-metal and dependencies
+# Creates a self-contained tarball with a standalone Python 3.12 + vllm-metal packages.
+# The result can be extracted anywhere and run without any system Python dependency.
 #
 # Usage: ./scripts/build-vllm-metal-tarball.sh <VLLM_METAL_RELEASE> <TARBALL>
 #   VLLM_METAL_RELEASE - vllm-metal release tag (required)
 #   TARBALL - Output tarball path (required)
 #
 # Requirements:
 #   - macOS with Apple Silicon (ARM64)
-#   - Python 3.12+ installed (standard on macOS 14+, or via Homebrew)
 #   - uv (will be installed if missing)
 
 set -e
 
 VLLM_METAL_RELEASE="${1:?Usage: $0 <VLLM_METAL_RELEASE> <TARBALL>}"
 TARBALL_ARG="${2:?Usage: $0 <VLLM_METAL_RELEASE> <TARBALL>}"
 WORK_DIR=$(mktemp -d)
-VENV_DIR="$WORK_DIR/venv"
 
 # Convert tarball path to absolute before we cd elsewhere
 TARBALL="$(cd "$(dirname "$TARBALL_ARG")" && pwd)/$(basename "$TARBALL_ARG")"
@@ -37,56 +36,52 @@ if ! command -v uv &> /dev/null; then
     export PATH="$HOME/.local/bin:$PATH"
 fi
 
-# Python 3.12 required (vllm-metal wheel is built for cp312)
-if command -v python3.12 &> /dev/null; then
-    PYTHON_BIN="python3.12"
-elif command -v python3 &> /dev/null && [ "$(python3 --version 2>&1 | grep -oE '[0-9]+\.[0-9]+')" = "3.12" ]; then
-    PYTHON_BIN="python3"
-else
-    echo "Error: Python 3.12 is required (the vllm-metal wheel is built for cp312)"
-    echo "Install with: brew install python@3.12"
-    exit 1
-fi
+# Install standalone Python 3.12 via uv (from python-build-standalone, relocatable)
+echo "Installing standalone Python 3.12 via uv..."
+uv python install 3.12
 
-PYTHON_VERSION=$($PYTHON_BIN --version 2>&1 | grep -oE '[0-9]+\.[0-9]+')
-echo "Using Python $PYTHON_VERSION from: $(which $PYTHON_BIN)"
+PYTHON_BIN=$(uv python find 3.12)
+PYTHON_PREFIX=$(cd "$(dirname "$PYTHON_BIN")/.." && pwd)
+echo "Using standalone Python from: $PYTHON_PREFIX"
 
-echo "Creating Python venv..."
-uv venv "$VENV_DIR" --python "$PYTHON_BIN"
+# Copy the standalone Python to our work area
+PYTHON_DIR="$WORK_DIR/python"
+cp -Rp "$PYTHON_PREFIX" "$PYTHON_DIR"
 
-export VIRTUAL_ENV="$VENV_DIR"
-export PATH="$VENV_DIR/bin:$PATH"
+# Remove the externally-managed marker so we can install packages into it
+rm -f "$PYTHON_DIR/lib/python3.12/EXTERNALLY-MANAGED"
 
 echo "Installing vLLM $VLLM_VERSION from source (CPU requirements)..."
 cd "$WORK_DIR"
 curl -fsSL -O "https://github.com/vllm-project/vllm/releases/download/v$VLLM_VERSION/vllm-$VLLM_VERSION.tar.gz"
 tar xf "vllm-$VLLM_VERSION.tar.gz"
 cd "vllm-$VLLM_VERSION"
-uv pip install -r requirements/cpu.txt --index-strategy unsafe-best-match
-uv pip install .
+uv pip install --python "$PYTHON_DIR/bin/python3" --system -r requirements/cpu.txt --index-strategy unsafe-best-match
+uv pip install --python "$PYTHON_DIR/bin/python3" --system .
 cd "$WORK_DIR"
 rm -rf "vllm-$VLLM_VERSION" "vllm-$VLLM_VERSION.tar.gz"
 
 echo "Installing vllm-metal from pre-built wheel..."
 curl -fsSL -O "$VLLM_METAL_WHEEL_URL"
-uv pip install vllm_metal-*.whl
+uv pip install --python "$PYTHON_DIR/bin/python3" --system vllm_metal-*.whl
 rm -f vllm_metal-*.whl
 
-echo "Packaging site-packages..."
-SITE_PACKAGES_DIR="$VENV_DIR/lib/python$PYTHON_VERSION/site-packages"
-if [ ! -d "$SITE_PACKAGES_DIR" ]; then
-    echo "Error: site-packages directory not found at $SITE_PACKAGES_DIR"
-    exit 1
-fi
+# Strip files not needed at runtime to reduce tarball size
+echo "Stripping unnecessary files..."
+rm -rf "$PYTHON_DIR/include"
+rm -rf "$PYTHON_DIR/share"
+PYLIB="$PYTHON_DIR/lib/python3.12"
+rm -rf "$PYLIB/test" "$PYLIB/tests"
+rm -rf "$PYLIB/idlelib" "$PYLIB/idle_test"
+rm -rf "$PYLIB/tkinter" "$PYLIB/turtledemo"
+rm -rf "$PYLIB/ensurepip"
+find "$PYTHON_DIR" -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
 
-tar -czf "$TARBALL" -C "$SITE_PACKAGES_DIR" .
+echo "Packaging standalone Python with vllm-metal..."
+tar -czf "$TARBALL" -C "$PYTHON_DIR" .
 
 SIZE=$(du -h "$TARBALL" | cut -f1)
 echo "Created: $TARBALL ($SIZE)"
 echo ""
-echo "To use this tarball:"
-echo "  1. Upload to GitHub releases"
-echo "  2. Model-runner will auto-download on first use"
-echo "  3. Or manually extract for testing:"
-echo "     python3.12 -m venv ~/.model-runner/vllm-metal"
-echo "     tar -xzf $TARBALL -C ~/.model-runner/vllm-metal/lib/python$PYTHON_VERSION/site-packages/"
+echo "This tarball is fully self-contained (includes Python 3.12 + all packages)."
+echo "To use: extract to a directory and run bin/python3 -m vllm_metal.server"