本文整理在 Windows、Linux 和 macOS 上使用 Colab CLI 和 VS Code Remote SSH 的常用命令:创建 GPU 会话、配置 SSH 主机入口、打开远程目录,以及挂载 Google Drive 保存代码、数据和模型。
Colab CLI 命令以 google-colab-cli 0.7.5 为例。Windows 使用 PowerShell 7,Linux 使用 Bash,macOS 可使用默认的 Zsh。没有系统专用路径或变量的 colab、ssh、code 命令在三个系统上写法相同;标注“远端”的命令在 Colab 的 Linux 终端中执行。
一、安装工具与登录
Windows 安装
在已安装 uv 和 VS Code 的本机执行:
# 安装 Google Cloud CLI
winget install --id Google.CloudSDK --exact --source winget
# 安装 Colab CLI
uv tool install google-colab-cli
# 安装 VS Code Remote SSH 扩展
code --install-extension ms-vscode-remote.remote-ssh
安装后重新打开 PowerShell,检查命令是否可用:
gcloud --version
colab version
Get-Command colab, ssh, code
Linux 安装
以下以 Ubuntu/Debian 为例。先安装 OpenSSH 客户端及安装工具,再按 Google 的 APT 仓库方式安装 Cloud CLI;已经配置过该仓库时跳过添加步骤:
# 本地 Linux 终端
sudo apt-get update
sudo apt-get install -y ca-certificates gnupg curl openssh-client unzip
# 导入 Google Cloud 仓库密钥
curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg \
| sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
# 添加仓库
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" \
| sudo tee /etc/apt/sources.list.d/google-cloud-sdk.list
sudo apt-get update
sudo apt-get install -y google-cloud-cli
其他发行版可以选择官方提供的压缩包或相应包管理器安装方式。Google Cloud CLI 安装说明
安装 uv 和 Colab CLI:
# 本地 Linux 终端
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
uv tool install google-colab-cli
uv tool update-shell
uv tool update-shell 按需更新终端启动配置,使后续终端也能找到工具。VS Code 请先按其 Linux 安装说明安装,再执行下面的扩展安装命令。uv 安装说明、VS Code Linux 安装说明
code --install-extension ms-vscode-remote.remote-ssh
macOS 安装
已安装 Homebrew 时,在本地终端执行:
brew install uv
brew install --cask gcloud-cli
# 尚未安装 VS Code 时执行
brew install --cask visual-studio-code
uv tool install google-colab-cli
export PATH="$HOME/.local/bin:$PATH"
uv tool update-shell
当前 Google Cloud CLI 的 Homebrew cask 名称是 gcloud-cli。Homebrew 软件包说明
打开 VS Code,按 Cmd+Shift+P,搜索 Shell Command,执行安装 code 命令到 PATH 的选项,然后重新打开终端。VS Code macOS 命令行配置
code --install-extension ms-vscode-remote.remote-ssh
Linux/macOS 检查命令
gcloud --version
colab version
command -v colab
command -v ssh
command -v code
Colab CLI 官方目前列出的支持平台是 Linux 和 macOS;本文中的 Windows 用法来自本机已成功连接的配置。Colab CLI 官方说明
Google 身份认证
三个系统都可以执行同一条 ADC 登录命令:
gcloud auth application-default login --scopes=openid,https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/colaboratory
按浏览器提示完成登录,再查看会话:
colab sessions
这一步用于 Colab CLI 的身份认证;后面的 Drive 挂载还需要单独授权。认证参数说明
准备 SSH 密钥
已有可用的 Ed25519 密钥时直接使用。仅在密钥文件不存在时创建,按提示设置口令:
New-Item -ItemType Directory -Path "$env:USERPROFILE\.ssh" -Force | Out-Null
ssh-keygen -t ed25519 -f "$env:USERPROFILE\.ssh\id_ed25519"
后面的配置统一使用 ~/.ssh/id_ed25519。如果换用其他密钥路径,需要同时修改 IdentityFile 和 ProxyCommand 中的 --identity。
Linux/macOS 在本地终端使用下面的命令,已有密钥时跳过创建:
mkdir -p "$HOME/.ssh"
chmod 700 "$HOME/.ssh"
if [ ! -f "$HOME/.ssh/id_ed25519" ]; then
ssh-keygen -t ed25519 -f "$HOME/.ssh/id_ed25519"
fi
chmod 600 "$HOME/.ssh/id_ed25519"
二、创建和管理 Colab 会话
本节命令适用于 Windows PowerShell、Linux Bash 和 macOS Zsh,选择需要的命令执行即可。
创建运行时
按需要选择其中一条执行;每条 new 命令都会申请新的运行时资源:
# CPU 会话
colab new -s colab
# GPU 会话,选择需要的型号
colab new -s colab-g4 --gpu G4
colab new -s colab-h100 --gpu H100
colab new -s colab-a100 --gpu A100
colab new -s colab-l4 --gpu L4
colab new -s colab-t4 --gpu T4
-s 指定会话名,--gpu 指定新运行时的 GPU 类型。实际分配受账号权限、算力额度和资源供应影响。
查看会话和打开网页
下面以 colab-g4 为例;使用其他会话时替换名称即可:
# 列出会话
colab sessions
# 查看指定会话状态
colab status -s colab-g4
# 显示连接到该会话的 Colab 网页地址
colab url -s colab-g4
停止会话
确认任务已结束、需要的文件已经保存后执行:
colab stop -s colab-g4
关闭 SSH 终端或 VS Code 窗口不会自动停止运行时。/content 是运行时本地目录,需要长期保留的文件应存入云盘或下载到本地。
三、SSH config 完整示例
Windows 用户的 SSH 配置文件是:
%USERPROFILE%\.ssh\config
可以通过 VS Code 打开编辑:
code "$env:USERPROFILE\.ssh\config"
Linux/macOS 的配置文件是 ~/.ssh/config,可以这样准备并打开:
mkdir -p "$HOME/.ssh"
chmod 700 "$HOME/.ssh"
touch "$HOME/.ssh/config"
chmod 600 "$HOME/.ssh/config"
code "$HOME/.ssh/config"
将需要的主机条目合并到配置文件中;已有同名 Host 时修改原条目,避免重复。下面先给出 Windows 版的一个基础入口和五个 GPU 入口:
# 基础会话
Host colab
HostName colab-runtime
User root
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
ProxyCommand colab ssh --proxy-mode -s colab --identity ~/.ssh/id_ed25519
StrictHostKeyChecking no
UserKnownHostsFile NUL
ServerAliveInterval 30
ServerAliveCountMax 3
ConnectTimeout 60
# G4
Host colab-g4
HostName colab-runtime
User root
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
ProxyCommand colab ssh --proxy-mode -s colab-g4 --gpu G4 --identity ~/.ssh/id_ed25519
StrictHostKeyChecking no
UserKnownHostsFile NUL
ServerAliveInterval 30
ServerAliveCountMax 3
ConnectTimeout 120
# H100
Host colab-h100
HostName colab-runtime
User root
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
ProxyCommand colab ssh --proxy-mode -s colab-h100 --gpu H100 --identity ~/.ssh/id_ed25519
StrictHostKeyChecking no
UserKnownHostsFile NUL
ServerAliveInterval 30
ServerAliveCountMax 3
ConnectTimeout 120
# A100
Host colab-a100
HostName colab-runtime
User root
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
ProxyCommand colab ssh --proxy-mode -s colab-a100 --gpu A100 --identity ~/.ssh/id_ed25519
StrictHostKeyChecking no
UserKnownHostsFile NUL
ServerAliveInterval 30
ServerAliveCountMax 3
ConnectTimeout 120
# L4
Host colab-l4
HostName colab-runtime
User root
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
ProxyCommand colab ssh --proxy-mode -s colab-l4 --gpu L4 --identity ~/.ssh/id_ed25519
StrictHostKeyChecking no
UserKnownHostsFile NUL
ServerAliveInterval 30
ServerAliveCountMax 3
ConnectTimeout 120
# T4
Host colab-t4
HostName colab-runtime
User root
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
ProxyCommand colab ssh --proxy-mode -s colab-t4 --gpu T4 --identity ~/.ssh/id_ed25519
StrictHostKeyChecking no
UserKnownHostsFile NUL
ServerAliveInterval 30
ServerAliveCountMax 3
ConnectTimeout 120
Linux/macOS 配置示例
Linux/macOS 使用上面相同的主机别名、会话名和 GPU 参数,将每个条目的 UserKnownHostsFile NUL 改为 UserKnownHostsFile /dev/null。以 G4 为例:
Host colab-g4
HostName colab-runtime
User root
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
ProxyCommand colab ssh --proxy-mode -s colab-g4 --gpu G4 --identity ~/.ssh/id_ed25519
StrictHostKeyChecking no
UserKnownHostsFile /dev/null
ServerAliveInterval 30
ServerAliveCountMax 3
ConnectTimeout 120
附件的 ssh-config.unix.example 提供了六个完整入口,ssh-config.example 为 Windows 版。三个系统对应的文件位置和写法如下:
| 项目 | Windows PowerShell | Linux / macOS |
|---|---|---|
| 用户主目录变量 | $env:USERPROFILE |
$HOME 或 ~ |
| SSH 配置文件 | %USERPROFILE%\.ssh\config |
~/.ssh/config |
| 默认私钥 | ~/.ssh/id_ed25519 |
~/.ssh/id_ed25519 |
| 空设备 | NUL |
/dev/null |
| 当前目录文件路径 | .\job.py |
./job.py |
| 多行命令续行 | PowerShell 的反引号 | Bash/Zsh 的反斜杠 \ |
VS Code 需要能从本地 PATH 找到 colab。需要写绝对路径时,先用 Windows 的 Get-Command colab 或 Linux/macOS 的 command -v colab 查询,再替换 ProxyCommand 开头的可执行文件路径;包含空格的路径加双引号。
参数含义
| 配置项 | 作用 |
|---|---|
Host |
本机连接时使用的主机别名,例如 ssh colab-g4 |
HostName |
SSH 使用的目标主机标识;本例实际连接由代理命令建立 |
User root |
远端登录用户 |
IdentityFile |
本机 OpenSSH 使用的私钥 |
IdentitiesOnly yes |
限定 SSH 使用配置的身份,减少其他密钥的尝试 |
ProxyCommand |
通过 Colab CLI 建立 SSH 数据通道 |
--proxy-mode |
将 SSH 标准输入输出接到 Colab 通道 |
-s |
选择 Colab 会话名 |
--gpu |
会话不存在时,创建运行时所用的 GPU 类型 |
--identity |
Colab CLI 使用的密钥路径,与 IdentityFile 保持一致 |
StrictHostKeyChecking no |
放宽服务器主机密钥检查 |
UserKnownHostsFile NUL |
将用户级主机记录指向 Windows 空设备 |
ServerAliveInterval 30 |
每隔 30 秒发送一次保活请求 |
ServerAliveCountMax 3 |
连续 3 次保活未获回应后断开 |
ConnectTimeout |
SSH 连接超时,单位为秒 |
--gpu 只在创建新会话时生效。 已有会话会被复用;修改这一项不会将现有运行时原地更换为另一种 GPU。为不同显卡使用不同会话名即可。SSH 选项与会话创建逻辑
NUL 是 Windows 写法,Linux/macOS 通常使用 /dev/null。上面的主机密钥配置适用于本文临时运行时的使用方式,会降低服务器身份核验强度;保活参数也不会延长平台规定的运行时寿命。
使用配置连接
按需要选择一个入口:
ssh colab
ssh colab-g4
ssh colab-h100
ssh colab-a100
ssh colab-l4
ssh colab-t4
GPU 入口在会话不存在时可以自动申请对应运行时。连接后,在远端确认实际显卡:
nvidia-smi
四、直接使用 SSH 命令
临时连接时,也可以不写入 config,直接传入参数。Windows PowerShell:
ssh -i "$env:USERPROFILE\.ssh\id_ed25519" -o IdentitiesOnly=yes -o ProxyCommand="colab ssh --proxy-mode -s colab-g4 --gpu G4 --identity ~/.ssh/id_ed25519" -o StrictHostKeyChecking=no -o UserKnownHostsFile=NUL root@colab-runtime
Linux/macOS 本地终端:
ssh -i "$HOME/.ssh/id_ed25519" \
-o IdentitiesOnly=yes \
-o ProxyCommand="colab ssh --proxy-mode -s colab-g4 --gpu G4 --identity ~/.ssh/id_ed25519" \
-o StrictHostKeyChecking=no \
-o UserKnownHostsFile=/dev/null \
root@colab-runtime
这些命令与前面的 colab-g4 配置作用相同,日常使用 ssh colab-g4 更方便。
五、VS Code 打开远程目录
通过命令面板执行 Remote-SSH: Connect to Host...,选择相应主机后,再执行“打开文件夹”。以下命令在 Windows、Linux、macOS 的本地终端中都可直接指定远程目录:
# 基础会话,打开 /content
code --remote ssh-remote+colab /content
# G4 会话,打开 /content
code --remote ssh-remote+colab-g4 /content
# H100 会话,打开 /content
code --remote ssh-remote+colab-h100 /content
使用远程文件夹 URI,可以在新窗口中打开:
code --new-window --folder-uri vscode-remote://ssh-remote+colab/content
远程目录由 VS Code 的参数指定;SSH config 保持前面的连接配置即可。VS Code 官方命令行用法
六、挂载同一个 Google Drive
挂载命令和路径
在任一系统的本地终端中,为需要使用的会话挂载云盘:
colab drivemount -s colab /content/drive
换成其他会话时,相应替换 -s 后的名称:
colab drivemount -s colab-g4 /content/drive
colab drivemount -s colab-h100 /content/drive
出现授权提示后,在浏览器中选择存放项目的同一个 Google 账号,完成授权并回到终端按 Enter。每个新运行时都需要分别挂载。
挂载后,“我的云端硬盘”的路径是:
/content/drive/MyDrive
共享工作区
本文配套脚本使用以下目录:
/content/drive/MyDrive/ColabWorkspace
├── code/ 代码
├── data/ 数据集
├── models/ 模型权重与适配器
├── checkpoints/ 训练检查点
├── outputs/ 日志、图表与导出结果
└── env/ 依赖清单与初始化脚本
每个运行时都用 /content/workspace 软链接指向这个根目录,代码里即可使用相同路径。
下载共享工作区脚本与 SSH 配置示例。Windows 用户将压缩包解压到:
%USERPROFILE%\Documents\Colab
先将附件中的 SSH 配置合并到本机 config,再在本地运行启动脚本:
# 使用已有的基础会话
& "$env:USERPROFILE\Documents\Colab\Open-ColabWorkspace.ps1" -Session colab
# 使用 G4 入口;会话不存在时会申请 GPU 资源
& "$env:USERPROFILE\Documents\Colab\Open-ColabWorkspace.ps1" -Session colab-g4
# 使用 H100 入口
& "$env:USERPROFILE\Documents\Colab\Open-ColabWorkspace.ps1" -Session colab-h100
脚本完成挂载检查、共享目录初始化和工作区标识核对,然后打开 VS Code。基础入口 colab 要求会话已经存在,五个 GPU 入口可在会话不存在时自动创建。
其他可选用法:
# 只准备工作区,不打开 VS Code
& "$env:USERPROFILE\Documents\Colab\Open-ColabWorkspace.ps1" -Session colab-g4 -NoOpen
# 已挂载时检查并准备工作区;未挂载则报错
& "$env:USERPROFILE\Documents\Colab\Open-ColabWorkspace.ps1" -Session colab-g4 -NoOpen -NoMount
-NoOpen 和 -NoMount 都不会禁止缺失 GPU 会话的自动创建。
Linux/macOS 准备共享工作区
将下载的压缩包解压到本地目录:
mkdir -p "$HOME/Documents/Colab"
unzip "$HOME/Downloads/colab-workspace-tools.zip" -d "$HOME/Documents/Colab"
先把 ssh-config.unix.example 中需要的条目合并到 ~/.ssh/config。对应会话已创建后,在本地终端依次挂载云盘、执行远端初始化脚本,再打开 VS Code:
# 选择已有会话,也可以改成 colab-h100 等名称
session=colab-g4
# 完成浏览器授权后,回到此终端按 Enter
colab drivemount -s "$session" /content/drive
# 读取本地脚本,在 Colab 运行时中初始化共享目录
colab exec -s "$session" --timeout 180 \
-f "$HOME/Documents/Colab/Initialize-Workspace.py"
确认初始化成功后打开远程目录:
code --remote "ssh-remote+$session" /content/workspace
初始化会输出 COLAB_WORKSPACE_READY=1 和工作区标识。不同运行时使用同一个 Google 账号,并比对工作区标识;此手动流程需要自行核对,Windows 启动脚本会自动比较本地保存的标识。
工作区准备完成后,也可直接打开:
code --remote ssh-remote+colab-g4 /content/workspace
共享目录会保留代码、数据和检查点;新运行时的 Python 包需要重新安装,训练也需要从已保存的检查点显式恢复。多个任务使用各自的输出子目录,避免同时写入同一文件。
七、执行代码和安装依赖
从本地提交 Python 脚本
# 读取本地 job.py,提交到指定会话的 Python 内核执行
# 此处将等待超时设为 300 秒
colab exec -s colab-g4 --timeout 300 -f .\job.py
Linux/macOS 将本地路径写为 ./job.py:
colab exec -s colab-g4 --timeout 300 -f ./job.py
exec 的默认执行超时为 30 秒,可按任务时长调整;长时间训练可以在 VS Code 的远端终端中启动。
从本地安装依赖清单
# requirements.txt 是本地文件
colab install -s colab-g4 -r .\requirements.txt
Linux/macOS 本地终端:
colab install -s colab-g4 -r ./requirements.txt
使用共享工作区中的依赖清单时,先填入项目实际使用的包和版本,再在远端执行:
python -m pip install -r /content/workspace/env/requirements.txt
# 或执行配套初始化脚本生成的安装入口
bash /content/workspace/env/bootstrap.sh
八、传输文件和导出执行历史
在本地执行,两个路径分别表示来源和目标:
# 上传:本地文件 → 远端文件
colab upload -s colab-g4 .\job.py /content/job.py
# 下载:远端文件 → 本地文件
colab download -s colab-g4 /content/result.json .\result.json
# 查看最近 20 条 CLI 执行记录
colab log -s colab-g4 -n 20
# 将 CLI 执行历史导出为本地 Notebook
colab log -s colab-g4 -o .\session.ipynb
Linux/macOS 本地终端使用正斜杠路径:
colab upload -s colab-g4 ./job.py /content/job.py
colab download -s colab-g4 /content/result.json ./result.json
colab log -s colab-g4 -n 20
colab log -s colab-g4 -o ./session.ipynb
upload 和 download 的示例针对单个文件;共享云盘中的项目也可以直接在 VS Code 中编辑。log 导出的是 CLI 记录的会话历史。
九、日常使用顺序
SSH config 和配套脚本准备好后,Windows 日常操作可以简化为:
# 1. 查看已有会话
colab sessions
# 2. 准备共享工作区并打开 VS Code
& "$env:USERPROFILE\Documents\Colab\Open-ColabWorkspace.ps1" -Session colab-g4
Linux/macOS 在本地终端使用:
colab sessions
colab drivemount -s colab-g4 /content/drive
colab exec -s colab-g4 --timeout 180 \
-f "$HOME/Documents/Colab/Initialize-Workspace.py" \
&& code --remote ssh-remote+colab-g4 /content/workspace
在打开的远端终端中执行:
# 3. 确认显卡并进入项目目录
nvidia-smi
cd /content/workspace
# 4. 安装项目依赖
bash env/bootstrap.sh
# 5. 运行自己的脚本,路径按项目结构修改
python code/train.py
任务结束、文件保存完成后,回到本地停止对应运行时:
colab stop -s colab-g4
平时主要使用三类入口:colab 命令管理运行时,ssh 或 VS Code 连接指定会话,共享工作区脚本准备云盘目录。更换显卡时替换会话名,继续打开同一个 /content/workspace,即可复用已保存的项目文件。