Take the first steps

Getting started

Set up your Linux container and install helpful development tools on capable Chrome OS devices.

Install Linux (Debian)

First, go to Chrome Settings and “turn on” Linux:

Linux (Beta)

Chrome OS will automatically download the necessary files and set up your Linux Container.

  1. When it finishes, you’ll see an open terminal window.
  2. Right-click on the terminal icon and choose “Pin” as a handy way to access your Linux container in the future.
Pin To Shelf

Now, your Debian Linux installation is ready to go! To give it a first spin, try a few of your favorite terminal commands:

ps -A
ps -A > psdump.txt
ls -l
cat /proc/devices

Now, let’s install a text editor or two:

sudo apt install -y nano gedit bluefish
nano -w hello-linux.txt
gedit hello-linux.txt
bluefish hello-linux.html

Synaptic package manager

If you’re a command-line ninja, you’re all set. But if you don’t mind a little graphical organization from time to time, install Synaptic, a powerful package manager. Synaptic allows you to find and fix broken dependencies, add repos, and more:

sudo apt install -y gksu synaptic
gksudo synaptic

Basic build tools

We’ll dive into more specific detail for Web, Android, and games in the other guides. First, let’s make sure you’ve got the basics down.
In Synaptic, find and install build-essential and default-jdk. Or, use the command line:

sudo apt install -y build-essential
sudo apt install -y default-jdk

Other basic tools

Media and sound

Chrome OS allows for sound and media editing within your Linux container.
Install GIMP photo editor:

sudo apt install -y gimp

Install Inkscape vector graphics editor:

sudo apt install -y inkscape

Install Audacity sound editor:

sudo apt install -y audacity

Gnome Software Centre

Gnome Software Centre is a graphical package manager that makes browsing available software easy. Here’s how to install it:

sudo apt install -y gnome-software gksu
sudo apt update
gksudo gnome-software &


If Gnome Software Centre only shows previously installed applications on the first run, refresh the cache:

pkill gnome-software
sudo rm -r /var/cache/app-info
sudo appstreamcli refresh --force --verbose

Then, two-finger tap/right-click on the terminal icon, shut down your Linux container, and re-open the terminal to reboot the container.

Container manipulation*

*This is an advanced process that we don’t recommend for new Linux users.
You can customize and configure your Linux containers for an ideal set-up. Below are some examples of container manipulation you may want to try. Check out the documentation on running custom containers in Chrome OS for more details.

Manually starting the container

From a Chrome shell (Ctrl-Alt-T), stop and restart the penguin container:

vmc stop termina
vmc start termina
vmc container termina penguin

GPU acceleration (alpha)

Want to try (alpha) GPU acceleration? Restart the container with the --enable-gpu flag:

vmc stop termina
vmc start --enable-gpu termina
vmc container termina penguin

Then, install updated mesa drivers inside the container:

sudo apt update
sudo apt install -y cros-gpu-alpha mesa-utils
sudo apt update
sudo apt dist-upgrade

Now, your apps and games should run with GPU acceleration. Give it a shot with Tux Racer:

sudo apt install -y extremetuxracer

Note: This feature is in active development and specific commands are likely to change. Expect glitches and breakage.

Other Linux containers

When you enable Linux on Chrome OS, a Debian “stretch” distribution is installed. This is built on top of your Linux container, so any of the supported container images can be used to easily install a different distribution including: Gentoo, Ubuntu, Fedora, Alpine, CentOS, openSUSE, and Arch Linux. Chrome OS aims to integrate the default container image as tightly as possible. However, with non-default images, expect some rough edges and unexpected container behavior.
Let’s go through the steps of installing the latest release of Ubuntu: disco (instructions adapted from the step-by-step guide here).
First, open a Chrome shell (Ctrl-Alt-T) and enter the VM, terminal:

vsh termina

Next, choose the LXC image you want to use:

lxc image copy images:ubuntu/disco local: --alias disco
lxc launch disco discotheque
lxc exec discotheque -- bash

You’re in! Now, install the packages to glue your Linux container and Chrome OS together.
*There may be some warning messages during these steps if this is not a Debian distribution. They should be safe to ignore in most cases.
First, set up the package lists and get the prerequisites:

sudo apt update && sudo apt upgrade
sudo echo "deb https://storage.googleapis.com/cros-packages stretch main" > /etc/apt/sources.list.d/cros.list
if [ -f /dev/.cros_milestone ]; then sudo sed -i "s?packages?packages/$(cat /dev/.cros_milestone)?" /etc/apt/sources.list.d/cros.list; fi
sudo apt install -y gnupg2 psmisc
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 1397BC53640DB551
sudo apt update
sudo apt install -y binutils
sudo apt download cros-ui-config
ar x cros-ui-config_0.12_all.deb data.tar.gz
gunzip data.tar.gz
tar f data.tar --delete ./etc/gtk-3.0/settings.ini
gzip data.tar
ar r cros-ui-config_0.12_all.deb data.tar.gz
rm -rf data.tar.gz

Now, install the packages you need and configure the GUI:

sudo apt install -y cros-adapta cros-apt-config cros-garcon cros-guest-tools cros-sftp cros-sommelier cros-sommelier-config cros-sudo-config cros-systemd-overrides ./cros-ui-config_*.deb cros-wayland
rm -rf cros-ui-config_*.deb
sudo sed -i 's/Ambiance/CrosAdapta/' /etc/gtk-3.0/settings.ini
sudo sed -i 's/ubuntu-mono-dark/CrosAdapta/' /etc/gtk-3.0/settings.ini
sudo sed -i 's/gtk-sound-theme-name = ubuntu/gtk-font-name = Roboto 11/' /etc/gtk-3.0/settings.ini
sudo sed -i '5d' /etc/gtk-3.0/settings.ini
sudo sed -i -n '2{h;n;G};p' /etc/gtk-3.0/settings.ini

Configure the container to use your Chrome login name as the default ubuntu username:

sudo killall -u ubuntu
sudo groupmod -n myusername ubuntu
sudo usermod -md /home/myusername -l myusername ubuntu
sudo usermod -aG users myusername
sudo loginctl enable-linger myusername

Shut down the new container:

sudo shutdown -h now

Now, you have Ubuntu disco running in the container discotheque. If you want to make this your default Linux container, do the following from Termina (you should be in Termina after the previous commands. If not, open a Chrome shell with Ctrl-Alt-T and type ‘vsh termina’):

lxc stop --force penguin
lxc rename penguin penguin-backup
lxc rename discotheque penguin

Log out or reboot, log in, and run the Terminal. Now you should be in your new environment!
Here’s how you can double-check:

lsb_release -a

Now that your Ubuntu environment is ready to go, a good first step is to install and try gedit:

sudo apt install -y gedit
gedit &


Docker-CE should work without any modifications or workarounds.
First, remove any old versions:

sudo apt remove docker docker-engine docker.io containerd runc

Next, gather the prerequisites:

sudo apt update
sudo apt install -y apt-transport-https ca-certificates curl gnupg2 software-properties-common

Now, update the gpg keys and install docker.
Note the architecture in the second step; replace “amd64” with “armhf” or “arm64” as desired. You may also replace “stable” with “nightly” or “test:”

curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -
sudo add-apt-repository \
   "deb [arch=amd64] https://download.docker.com/linux/debian \
   $(lsb_release -cs) \
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io

Finally, here’s how you can make sure it all worked:

sudo docker run hello-world

More resources

How to Chromebook
Set up Linux (Beta) on your Chromebook
Running custom containers under Chrome OS
Linux (Beta) on Chrome OS reddit community