Let’s talk about something
Let’s talk about something
AboutContact
[1] 跟我一起学CUDA - 使用VSCode dev-container和Google Colab搭建免费的开发环境
👨‍💻

[1] 跟我一起学CUDA - 使用VSCode dev-container和Google Colab搭建免费的开发环境

Tags
CUDA
Published
December 29, 2025
Author
Also see English version:
👨‍💻
[1] Learning CUDA: a VS Code Dev Container + Google Colab Free-GPU Setup

简介

学习 CUDA 时，一个可用的 NVIDIA GPU 开发环境几乎是刚需。
但在本地搭建环境经常会踩坑：驱动与运行时版本不匹配、IDE/LSP 报错、容器与平台架构不兼容等。本文提供一套尽量开箱即用、并且能用 VS Code + Dev Container 在本地获得舒适编辑体验、再借助 Google Colab 的免费 GPU 完成编译与运行的方案。
💡
本文对 NVIDIA 开发工具与 Colab 的使用均遵循其用户协议。
本文仅展示交互式使用方式，不包含任何自动化或非交互式方式访问 Colab 的内容。

你需要提前具备

  • VS Code 的基础操作与常用设置
  • 基本的编译概念（编译、链接、可执行文件）
  • Jupyter Notebook 与 Google Colab 的基础使用
  • Docker Desktop 已安装并可正常启动

代码仓库

完整代码见：GitHub 仓库

1. 使用 Dev Container 准备 CUDA 开发环境（侧重编辑体验）

本节目标：
  • 在本地获得完整的编辑、跳转、格式化与 LSP 体验
  • 不要求本地具备可运行 CUDA 的 NVIDIA GPU（运行环节交由 Colab 完成）

1.1 创建 Dev Container 配置

在项目根目录创建：
mkdir -p .devcontainer
cd .devcontainer

1.2 Dockerfile（基于 NVIDIA 官方 CUDA 镜像）

在 .devcontainer 中创建 Dockerfile：
FROM nvidia/cuda:13.1.0-devel-ubuntu24.04

# Prevent interactive prompts
ENV DEBIAN_FRONTEND=noninteractive

# Install dependencies (wget/curl/git/zsh/sudo/clangd)
RUN apt-get update && \
    apt-get install -y wget curl git zsh sudo vim clangd && \
    rm -rf /var/lib/apt/lists/*

# Install Oh My Zsh
RUN sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended

# Force RobbyRussell theme and Git plugin
RUN sed -i 's/ZSH_THEME=".*"/ZSH_THEME="robbyrussell"/' ~/.zshrc && \
    sed -i 's/plugins=(.*)/plugins=(git)/' ~/.zshrc

# Set Zsh as default
RUN chsh -s $(which zsh)
这个镜像主要做了：
  • 以 nvidia/cuda:13.1.0-devel-ubuntu24.04 为基础镜像
  • 安装基础工具与 clangd（给 VS Code 的 C/C++ LSP 用）
  • 配置 zsh（个人偏好，可按需删除）

1.3 devcontainer.json（固定 x86_64，并安装常用扩展）

在 .devcontainer 中创建 devcontainer.json：
{
	"name": "CUDA Dev (Compile Only)",
	"build": {
		"dockerfile": "Dockerfile",
		"options": [
			"--platform=linux/amd64"
		]
	},
	"runArgs": [
		"--platform=linux/amd64"
	],
	"customizations": {
		"vscode": {
			"extensions": [
				"llvm-vs-code-extensions.vscode-clangd",
				"nshen.cpp-tools",
				"ms-toolsai.jupyter",
				"google.colab",
				"nvidia.nsight-vscode-edition",
				"NVIDIA.nsight-copilot",
				"GitHub.copilot",
				"GitHub.copilot-chat"
			],
			"settings": {
				"C_Cpp.intelliSenseEngine": "disabled",
				"clangd.path": "clangd",
				"clangd.arguments": [
					"--compile-commands-dir=${workspaceFolder}",
					"--background-index",
					"--header-insertion=never"
				],
				"terminal.integrated.defaultProfile.linux": "zsh"
			}
		}
	},
	"remoteUser": "root"
}

说明

  • 平台固定为 linux/amd64：在 Apple Silicon（ARM）环境下，部分 CUDA 镜像与工具链存在兼容性问题；固定为 x86_64 通常更稳定。
  • Nsight 扩展：用于 CUDA 开发、调试与性能分析；具体能力取决于运行环境与权限。

1.4 启动 Dev Container

在 VS Code 中按 Cmd + Shift + P，选择 Dev Containers: Reopen in Container。
在 macOS 下请确保 Docker Desktop 已启动。
notion image

2. 本地编写最小示例（验证编辑与编译链路）

在容器中创建 hello.cu：
#include <stdio.h>
#include <cuda_runtime.h>

__global__ void helloCUDA() {
    printf("Hello from GPU!\n");
}

int main() {
    printf("Hello from CPU!\n");

    // Launch kernel
    helloCUDA<<<1, 1>>>();

    // 1) Check launch errors
    cudaError_t err = cudaGetLastError();
    if (err != cudaSuccess) {
        printf("Kernel Launch Error: %s\n", cudaGetErrorString(err));
    }

    // 2) Check runtime errors
    err = cudaDeviceSynchronize();
    if (err != cudaSuccess) {
        printf("Runtime Error: %s\n", cudaGetErrorString(err));
    }

    return 0;
}
在终端里编译：
nvcc ./hello.cu -o hello.out
./hello.out
如果你的本机没有 NVIDIA GPU（或容器未接入 GPU），通常会看到类似：
Hello from CPU!
Kernel Launch Error: CUDA driver version is insufficient for CUDA runtime version
Runtime Error: CUDA driver version is insufficient for CUDA runtime version
这属于预期行为：本地容器主要用于提供编辑体验（LSP、补全、跳转、格式化）与编译工具链；运行阶段在后续通过 Colab 的 GPU 完成。
notion image

3. 使用 Colab GPU 编译并运行

本节目标：
  • 本地编写与管理代码
  • 在 Colab 侧完成 GPU 编译与执行

3.1 创建 Notebook 并选择 Colab Kernel

在项目根目录创建 hello.ipynb，然后在 VS Code 里选择 Kernel 为 Colab：
notion image
在 Colab 里选择 GPU（例如 T4）：
notion image
Kernel 选择 Python3 后，你应该能看到 GPU 相关信息输出：
notion image

3.2 把 Colab 文件系统挂载到本地工作区

在 VS Code 的 Colab 相关菜单中，选择把 Colab 会话的文件系统 attach 到当前 workspace：
notion image
注意：dev container 可能会在这个过程中触发 reload。reload 后需要重新选择最近使用的 Colab kernel/session。
notion image
挂载成功后，左侧文件树会出现 Colab 的文件系统：
notion image
你可以把 hello.cu 复制到 Colab 侧的目录中。实际上这一步不是必须的：
  • 如果你把代码放在 GitHub，也可以直接在 notebook 里 git clone。
  • 或者用 curl 下载单文件。

3.3 在 Colab 里编译并运行

在 Colab 环境中编译并运行（示意）：
notion image

版本兼容性：CUDA Toolkit 与驱动不匹配

在我写本文时（2025-12-29），Colab 环境里可能出现：
  • nvcc 对应的 CUDA toolkit/运行时版本较新
  • 但机器上的 GPU driver 版本略旧
这会导致直接编译运行时报错。
一种规避方式是让 nvcc 生成特定架构（例如 T4 对应 sm_75）的代码，例如：
nvcc -arch=sm_75 hello.cu -o hello.out
./hello.out
如果不指定，可能会出现类似报错：
notion image

4. 总结与局限

该方案的核心思路是：本地保障开发体验，运行与验证交由 Colab 完成。相较纯本地 GPU 环境，流程更复杂，但具备以下优势：
  • 不用本地安装 CUDA/驱动，也能先把 CUDA 写起来
  • 依然保留较好的 VS Code 体验
  • 需要 GPU 运行时再去 Colab 借用
局限也很明确：
  • dev container reload、kernel/session 重新选择会让体验略碎
  • 免费 GPU 资源不稳定，排队与配额不可控
毕竟这些都是免费的午餐🤷 
Copyright 2025 Ziyi Xi