Chromebook terminal notes — Crostini, VS Code, and common fixes

This page is written for brand-new CS1 students using a Chromebook. It groups common problems by scenario, explains in plain language what is happening and why the fix works, gives exact copy/paste commands, and shows how to verify the fix worked. Every troubleshooting tip includes at least one authoritative link.

Important course versions

  • Java: JDK 25 (Eclipse Temurin by Adoptium). See /setup/setup-jdk/ for downloads and instructions.
  • Gradle: Use the project wrapper — assignments use Gradle 9.2.0.

Quick glossary

  • Crostini / Linux (Beta): ChromeOS’s supported Linux container where you install developer tools (Debian/Ubuntu-like).
  • sshfs / remote: If you’re editing on a remote machine, VS Code can connect via Remote - SSH; this is an advanced option.

Scenario A — I don’t see a Linux (Beta) option in Settings

What you see

  • The Developers / Linux (Beta) option is missing in ChromeOS Settings.

Plain-language explanation

  • Some Chromebooks (managed devices or very old models) don’t support Crostini. You need either a supported device, admin permission, or to use a different workflow (remote development or another machine).

What to try

1) Check device support: https://chromium.googlesource.com/chromiumos/docs/+/HEAD/containers.md 2) If your device is managed (school account), ask your administrator to enable Linux apps.

How to tell it worked

  • After enabling, you will see a Terminal app in your launcher. Opening it gives you a shell prompt like username@penguin:~$.

Authoritative links

  • Chromebook Linux apps (Crostini): https://support.google.com/chromebook/answer/9145439

Scenario B — VS Code not installed inside Linux container or terminal not working

What you see

  • You installed VS Code on ChromeOS but can’t run ./gradlew or java --version in its terminal.

Plain-language explanation

  • VS Code installed on ChromeOS (outside the Linux container) doesn’t have access to the container’s Linux tools. You need VS Code inside the Linux container or use Remote → Connect to the container.

What to do (recommended)

  1. Open the Terminal app (Crostini) and install code-server or the official VS Code .deb inside the container following the VS Code Linux instructions.

Example (Debian/Ubuntu inside Crostini):

sudo apt update
sudo apt install -y wget gpg
wget -qO - https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > packages.microsoft.gpg
sudo install -o root -g root -m 644 packages.microsoft.gpg /usr/share/keyrings/
sudo sh -c 'echo "deb [arch=amd64 signed-by=/usr/share/keyrings/packages.microsoft.gpg] https://packages.microsoft.com/repos/code stable main" > /etc/apt/sources.list.d/vscode.list'
sudo apt update
sudo apt install -y code
  1. Launch VS Code from the container: code . and open the integrated terminal (Ctrl+`).

How to tell it worked

  • In the integrated terminal, java --version prints Temurin 25 and ./gradlew --version prints Gradle 9.2.0 (wrapper). echo hello prints hello.

Authoritative links

  • VS Code Linux install docs: https://code.visualstudio.com/docs/setup/linux

Scenario C — slow downloads or Gradle wrapper stalls

What you see

  • ./gradlew test takes a long time downloading dependencies or fails with network errors.

Plain-language explanation

  • The Gradle wrapper downloads Gradle and dependencies into ~/.gradle inside the container. On Chromebooks with limited storage or slow networks this can take a long time.

What to check

df -h ~
du -sh ~/.gradle || true
./gradlew --version --info

What to do

  • Free up space in the container or move the Gradle cache to a larger disk (advanced). Be patient on the first run — downloads may be hundreds of MB.

How to tell it worked

  • ./gradlew --version completes and ./gradlew test starts running tests instead of stalling on downloads.

Authoritative links

  • Gradle wrapper docs: https://docs.gradle.org/current/userguide/gradle_wrapper.html

Final checklist for Chromebook (step-by-step for new CS1 students)

  1. Enable Linux (Beta) / Crostini in ChromeOS settings and open the Terminal app.
  2. Install VS Code inside the Linux container or use Remote → SSH to a supported Linux machine.
  3. Install JDK 25 inside the container (follow /setup/setup-jdk/). Example for Debian: sudo apt install temurin-25-jdk after adding the Adoptium repository.
  4. In your assignment folder run: ./gradlew --version — expect Gradle 9.2.0.
  5. Run: ./gradlew test and allow the first-run downloads to complete.

If you hit an error, copy the exact error and post it on the course Discord with outputs of java --version and ./gradlew --version.

Authoritative references

  • Crostini / Linux apps: https://support.google.com/chromebook/answer/9145439
  • Adoptium Temurin: https://adoptium.net/
  • Gradle wrapper docs: https://docs.gradle.org/current/userguide/gradle_wrapper.html