Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here


Chromium OS Universal Chroot Environment

Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star half bd79095782ee4930099175e5ce7f4c89fa3ddabcd56fffcc7c74f6f2a2d46b27Star blank 374f33e4d622a2930833db3cbea26b5d03dc44961a6ecab0b9e13276d97d6682 (4 ratings)
Rated 3.5 out of 5
Subscribe to updates I use crouton

Statistics on crouton

Number of watchers on Github 6337
Number of open issues 533
Average time to close an issue 5 days
Main language Shell
Average time to merge a PR 12 days
Open pull requests 66+
Closed pull requests 28+
Last commit almost 2 years ago
Repo Created almost 7 years ago
Repo Last Updated over 1 year ago
Size 18.4 MB
Organization / Authordnschneid
Page Updated
Do you use crouton? Leave a review!
View open issues (533)
View crouton activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating crouton for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)
What people are saying about crouton Leave a review
Quit working...

crouton: Chromium OS Universal Chroot Environment

crouton is a set of scripts that bundle up into an easy-to-use, Chromium OS-centric chroot generator. Currently Ubuntu and Debian are supported (using debootstrap behind the scenes), but Chromium OS Debian, Ubuntu, and Probably Other Distros Eventually Chroot Environment doesn't acronymize as well (crodupodece is admittedly pretty fun to say, though). acronym?

It stands for ChRomium Os Universal chrooT envirONment ...or something like that. Do capitals really matter if caps-lock has been (mostly) banished, and the keycaps are all lower-case?

Moving on...

Who's this for?

Anyone who wants to run straight Linux on their Chromium OS device, and doesn't care about physical security. You're also better off having some knowledge of Linux tools and the command line in case things go funny, but it's not strictly necessary.

What's a chroot?

Like virtualization, chroots provide the guest OS with their own, segregated file system to run in, allowing applications to run in a different binary environment from the host OS. Unlike virtualization, you are not booting a second OS; instead, the guest OS is running using the Chromium OS system. The benefit to this is that there is zero speed penalty since everything is run natively, and you aren't wasting RAM to boot two OSes at the same time. The downside is that you must be running the correct chroot for your hardware, the software must be compatible with Chromium OS's kernel, and machine resources are inextricably tied between the host Chromium OS and the guest OS. What this means is that while the chroot cannot directly access files outside of its view, it can access all of your hardware devices, including the entire contents of memory. A root exploit in your guest OS will essentially have unfettered access to the rest of Chromium OS.

...but hey, you can run TuxRacer!


You need a device running Chromium OS that has been switched to developer mode.

For instructions on how to do that, go to this Chromium OS wiki page, click on your device model and follow the steps in the Entering Developer Mode section.

Note that developer mode, in its default configuration, is completely insecure, so don't expect a password in your chroot to keep anyone from your data. crouton does support encrypting chroots, but the encryption is only as strong as the quality of your passphrase. Consider this your warning.

It's also highly recommended that you install the crouton extension, which, when combined with the extension or xiwi targets, provides much improved integration with Chromium OS.

That's it! Surprised?


crouton is a powerful tool, and there are a lot of features, but basic usage is as simple as possible by design.

If you're just here to use crouton, you can grab the latest release from Download it, pop open a shell (Ctrl+Alt+T, type shell and hit enter), and run sh ~/Downloads/crouton to see the help text. See the examples section for some usage examples.

If you're modifying crouton, you'll probably want to clone or download the repo and then either run installer/ directly, or use make to build your very own crouton. You can also download the latest release, cd into the Downloads folder, and run sh crouton -x to extract out the juicy scripts contained within, but you'll be missing build-time stuff like the Makefile.

crouton uses the concept of targets to decide what to install. While you will have apt-get in your chroot, some targets may need minor hacks to avoid issues when running in the chrooted environment. As such, if you expect to want something that is fulfilled by a target, install that target when you make the chroot and you'll have an easier time. Don't worry if you forget to include a target; you can always update the chroot later and add it. You can see the list of available targets by running sh ~/Downloads/crouton -t help.

Once you've set up your chroot, you can easily enter it using the newly-installed enter-chroot command, or one of the target-specific start* commands. Ta-da! That was easy.


The easy way (assuming you want an Ubuntu LTS with Xfce)

  1. Download crouton
  2. Open a shell (Ctrl+Alt+T, type shell and hit enter) and run sudo sh ~/Downloads/crouton -t xfce
  3. Wait patiently and answer the prompts like a good person.
  4. Done! You can jump straight to your Xfce session by running sudo enter-chroot startxfce4 or, as a special shortcut, sudo startxfce4
  5. Cycle through Chromium OS and your running graphical chroots using Ctrl+Alt+Shift+Back and Ctrl+Alt+Shift+Forward.
  6. Exit the chroot by logging out of Xfce.

With encryption!

  1. Add the -e parameter when you run crouton to create an encrypted chroot or encrypt a non-encrypted chroot.
  2. You can get some extra protection on your chroot by storing the decryption key separately from the place the chroot is stored. Use the -k parameter to specify a file or directory to store the keys in (such as a USB drive or SD card) when you create the chroot. Beware that if you lose this file, your chroot will not be decryptable. That's kind of the point, of course.

Hey now, Ubuntu 16.04 is pretty old; I'm young and hip

  1. The -r parameter specifies which distro release you want to use.
  2. Run sh ~/Downloads/crouton -r list to list the recognized releases and which distros they belong to.

Wasteful redundancies are wasteful: one clipboard, one browser, one window

  1. Install the crouton extension into Chromium OS.
  2. Add the extension or xiwi version to your chroot.
  3. Try some copy-pasta, or uninstall all your web browsers from the chroot.

Installing the extension and its target gives you synchronized clipboards, the option of using Chromium OS to handle URLs, and allows chroots to create graphical sessions as Chromium OS windows.

I don't always use Linux, but when I do, I use CLI

  1. You can save a chunk of space by ditching X and just installing command-line tools using -t core or -t cli-extra
  2. Enter the chroot in as many crosh shells as you want simultaneously using sudo enter-chroot
  3. Use the Crosh Window extension to keep Chromium OS from eating standard keyboard shortcuts.
  4. If you installed cli-extra, startcli will launch a new VT right into the chroot.

A new version of crouton came out; my chroot is therefore obsolete and sad

  1. Check for updates, download the latest version, and see what's new by running croutonversion -u -d -c from the chroot (run croutonversion -h to see what those parameters actually do).
  2. Exit the chroot and run sudo sh ~/Downloads/crouton -u -n chrootname. It will update all installed targets.

I want to open my desktop in a window or a tab but I don't have the 'xiwi' target/xmethod.

  1. Add 'xiwi' or any other target to an existing chroot with the '-u' option using: sudo sh ~/Downloads/crouton -t xiwi -u -n chrootname

This will also make 'xiwi' the default xmethod.

  1. If you want to keep the 'xorg' xmethod as the default then enter it first using: sudo sh ~/Downloads/crouton -t xorg,xiwi -u -n chrootname

A backup a day keeps the price-gouging data restoration services away

  1. sudo edit-chroot -b chrootname backs up your chroot to a timestamped tarball in the current directory. Chroots are named either via the -n parameter when created or by the release name if -n was not specified.
  2. sudo edit-chroot -r chrootname restores the chroot from the most recent timestamped tarball. You can explicitly specify the tarball with -f
  3. If your machine is new, powerwashed, or held upside-down and shaken, you can use the crouton installer to restore a chroot and relevant scripts: sudo sh ~/Downloads/crouton -f mybackup.tar.gz

Unlike with Chromium OS, the data in your chroot isn't synced to the cloud.

This chroot's name/location/password/existence sucks. How to fix?

  1. Check out the edit-chroot command; it likely does what you need it to do.
  2. If you set a Chromium OS root password, you can change it with sudo chromeos-setdevpasswd
  3. You can change the password inside your chroot with passwd

I want to install the chroot to another location

  1. Use -p to specify the directory in which to install the chroot and scripts. Be sure to quote or escape spaces.
  2. When entering the chroot, either specify the full path of the enter-chroot or start* scripts (i.e. sudo sh /path/to/enter-chroot), or use the -c parameter to explicitly specify the chroots directory.

Downloading bootstrap files over and over again is a waste of time

  1. Download crouton
  2. Open a shell (Ctrl+Alt+T, type shell and hit enter) and run sudo sh ~/Downloads/crouton -d -f ~/Downloads/mybootstrap.tar.bz2
  3. Include the -r parameter if you want to specify for which release to prepare a bootstrap.
  4. You can then create chroots using the tarball by running sudo sh ~/Downloads/crouton -f ~/Downloads/mybootstrap.tar.bz2. Make sure you also specify the target environment with -t.

This is the quickest way to create multiple chroots at once, since you won't have to determine and download the bootstrap files every time.

Targets are cool. Abusing them for fun and profit is even cooler

  1. You can make your own target files (start by copying one of the existing ones) and then use them with any version of crouton via the -T parameter.

This is great for automating common tasks when creating chroots.

Help! I've created a monster that must be slain!

  1. The delete-chroot command is your sword, shield, and only true friend. sudo delete-chroot evilchroot
  2. It's actually just a shortcut to sudo edit-chroot -d evilchroot, which I suppose makes it a bit of a deceptive Swiss Army knife friend...still good?


  • Chroots are cheap! Create multiple ones using -n, break them, then make new, better ones!
  • You can change the distro mirror from the default by using -m
  • Want to use a proxy? -P lets you specify one (or disable it).
  • A script is installed in your chroot called brightness. You can assign this to keyboard shortcuts to adjust the brightness of the screen (e.g. brightness up) or keyboard (e.g. brightness k down).
  • Multiple monitors will work fine in the chroot, but you may have to switch to Chromium OS and back to enable them.
  • You can make commands run in the background so that you can close the terminal. This is particularly useful for desktop environments: try running sudo startxfce4 -b
  • Want to disable Chromium OS's power management? Run croutonpowerd -i
  • Only want power management disabled for the duration of a command? croutonpowerd -i command and arguments will automatically stop inhibiting power management when the command exits.
  • Have a Pixel or two or 4.352 million? -t touch improves touch support.
  • Want to share some files and/or folders between ChromeOS and your chroot?
    Check out the /etc/crouton/shares file, or read all about it in the wiki.
  • Want more tips? Check the wiki.


Running another OS in a chroot is a pretty messy technique (although it's hidden behind very pretty scripts), and these scripts are relatively new, so problems are not surprising. Check the issue tracker and file a bug if your issue isn't there. When filing a new bug, include the output of croutonversion run from inside the chroot or, if you cannot mount your chroot, include the output of cat /etc/lsb-release from Crosh.

I want to be a Contributor!

That's great! But before your code can be merged, you'll need to have signed the Individual Contributor License Agreement. Don't worry, it only takes a minute and you'll definitely get to keep your firstborn, probably. If you've already signed it for contributing to Chromium or Chromium OS, you're already done.

If you don't know what to do with your time as an official Contributor, here's some suggestions:

  • Really like a certain desktop environment? Fork crouton, add the target, and create a pull request.
  • Feel like hacking around with Chromium OS integration? Fork crouton, improve integration, and create a pull request.
  • Is your distro underrepresented? Want to contribute to the elusive and mythical beast known as croagh? Fork crouton, add the distro, and create a pull request.
  • Discovered a bug lurking within the scripts, or a papercut that bothers you just enough to make you want to actually do something about it? You guessed it: fork crouton, fix everything, and create a pull request.
  • Are most bugs too high-level for you to defeat? Grind up some EXP by using your fork to eat pie.

Are there other, non-Contributory ways I can help?


But how?

There's a way For Everyone to help!

  • Something broken? File a bug! Bonus points if you try to fix it. It helps if you provide the output of croutonversion (or the output of cat /etc/lsb-release from Crosh) when you submit the bug.
  • Want to try and break something? Look through requests for testing and then do your best to brutally rip the author's work to shreds.
  • Look through open issues and see if there's a topic or application you happen to have experience with. And then, preferably, share that experience with others.
  • Find issues that need wiki entries and add the relevant info to the wiki. Or just add things to/improve things in the wiki in general, but do try to keep it relevant and organized.
  • Really like a certain desktop environment, but not up for coding? Open or comment on a bug with steps to get things working well.
  • Hang out in the #crouton IRC channel on!


crouton (including this eloquently-written README) is copyright © 2016 The crouton Authors. All rights reserved. Use of the source code included here is governed by a BSD-style license that can be found in the LICENSE file in the source tree.

crouton open issues Ask a question     (View All Issues)
  • about 3 years Cycling between OS and chroots (Acer C730)
  • about 3 years edit-chroot, Command Not Found
  • about 3 years cursor issue after switch
  • about 3 years Too many instances of my chroot
  • about 3 years $CHROOT/sys does not automatically unmount, causes suspend/resume issues
  • about 3 years Installing xserver-xorg-legacy (part of the kali-linux meta package) breaks startxfce4
  • about 3 years UID 1000 not found in stretch
  • about 3 years '/dev/tty0 is not a directory' "cannot connect to x server" after using chroot once
  • about 3 years symlink loop when stored on usb
  • about 3 years debian sid -k proxy
  • about 3 years Mint PL0X?
  • about 3 years page up down home end keyboard keys
  • about 3 years kde on xenial not showing upper bar nor draggable
  • about 3 years Problems starting gnome-session
  • about 3 years Handle detection of really, really old releases
  • about 3 years Problem with permissions and Firefox in crouton
  • about 3 years Detect out-of-space condition on tests
  • about 3 years Wiki openconnect instructions' script doesn't work with systemd
  • about 3 years Remove support for non-freon builds
  • about 3 years OpenVPN through ChromeOS
  • about 3 years Allow launching graphical crouton from frecon
  • about 3 years arm: unity/xenial: Xorg dummy server needs to support DRI2 extension
  • about 3 years xfce chroot giving error on start with ASUS C100P
  • about 3 years vboxconfig fails please help!
  • about 3 years Kodi black screen...
  • about 3 years Trying to run rkt on Toshiba Chromebooks (intel Core i3)
  • about 3 years C201 HW Acceleration (GLES2) enabled, but logout to black screen
  • about 3 years No keyboard or mouse movement Acer Chromebook 14
  • about 3 years Lack of KVM Support for Chrome OS
  • about 3 years Problem GNOME - trusty - Crouton
crouton open pull requests (View All Pulls)
  • Change license to 2016
  • Fix package management error during xenial, wily setup
  • Remove xephyr support
  • vivid kde plasma fix
  • Size tests
  • Detect whether we are running in containers and act responsively.
  • Add color to the prompt asking for username
  • Changed gnome-session-fallback to gnome-session-flashback, same thing bu...
  • Unencrypted keys in user directory for single-password access (from #1399)
  • Add check for trusty, and install pulseaudio
  • Nudge display brightness on return to cros
  • Add support in croutoncycle for multiple displays
  • Experimental cmt target
  • Archlinux support
  • Audio auto update
  • Test if kernels are signed before setting dev_boot_signed_only=1
  • crouton in a separate partition
  • Support for systemd
  • Allow `enabled_` boolean to persist in extension
  • if netsurf-gtk not available, continue without it
  • Mate
  • LXQT
  • targets/audio: Define CRAS_SOCKET_FILE_DIR
  • Fix abnormal termination at calling readlink in croutonfindnacl.
  • Pass error messages to findnacld. (refs #2181)
  • Fix issue when SELinux is enabled
  • support for release names with a dash in it, such as 'kali-rolling'
  • Fix ARC / Google Play for Chrome OS crash when starting chroot
  • Add TuxRacer Wikipedia link and markdown adjustments
  • Add include guards to websocket.h
  • Update copyright year to 2016
  • Stop testing Wily; it's EOL
  • Acer Chromebook 14 (edgar) specific touchpad settings.
  • Add host-wayland
  • Fixed unity target install errors on ubuntu xenial
  • install "www-browser" symlink as well
  • Set default release to xenial
  • Fix GNOME fallback/flashback on trusty+,wheezy+,kali+
  • Allow aarch64 chroots
  • Small fix for edgar touchpad support
  • Added gtk2-engines-pixbuf to remove warnings in XFCE
  • Updated copyright year to 2017
  • Add Elementary Target
  • Create Android Studio target
  • Two minor pie fixes for #2148 and #2102
  • xiwi: patch with xf86-video-dummy-0.3.8
  • README: fix broken links
  • Add dialout group to sync, for use with programming microcontrollers
  • Gentoo Support
  • fix regex to be more robust
  • ubuntu/bootstrap: use debian repository api to get latest version
  • 🎁 Do not open until 2017-04-01! 🎁
  • Link user keychain to session keychain
  • Update LTS version in
  • Remove space to correct markdown link in README
  • Create
  • Fix horizontal scroll direction for xiwi
  • Use Downloads folder of the user who launched the chroot
  • Kodi - Open ports to allow smb/samba browsing
  • Stop using the intel driver
  • Add support for opensuse
  • 35-xorg: Fix vendor/device printout
  • src/freon.c: Check before extracting mode in open
  • Remove gksu from gtk-extra target for debian buster and kali-rolling
  • Install kwin when installing kde
  • add i3
crouton questions on Stackoverflow (View All Questions)
  • How to reset root password in crouton shell
  • Arduino IDE in Crouton
  • ERROR 2002 (HY000) on crouton ubuntu 12.04
  • Ubuntu (percise): libopenblas-dev not available (Chromebook/Crouton)
  • [Pyo/Jackd/PulseAudio]: Jack Error: Unabel to create JACK client (CromeOS/CROUTON/Precise)
  • wi-fi disconnected during crouton installation
  • Running Eclipse on HP 14 Chromebook with crouton and xfce. When ever I enter in Eclipse screen turns black
  • Android Crouton custom view doesn't allow text scrolling(marquee effect)
  • Chromebook chroot crouton several instances of linux at the same time
  • Ethereum - Disk space full on Chromebook, want to back up keystore on Linux (using Crouton)
  • Is it possible to use a progress bar in Crouton?
  • Android Studio on Chromebook with crouton-script (ARM-architecture)
  • Compile for Chromebook using Crouton
  • error 403 forbidden for CRAS in crouton
  • Push view down using Crouton library
  • Installing crouton error
  • Cron and Crouton (Chromebox)
  • .vimrc has no effect on Xubuntu running on crouton on Chromebook
  • crouton message is not shown when keyboard onscreen
  • How do I test a that crouton message ALERT was displayed using espresso
  • Crouton equivalence on iOS?
  • MongoDB - Xubuntu crouton - can't start service
  • Using custom style for the crouton library
  • How can I spawn an Android crouton from the bottom?
  • Crouton CustomView with infinit duration
  • Change value of an already displayed Crouton
  • Problems with Infinite Crouton in Android only appears once
  • Crouton with action bar overlay
  • Android: Crouton + Activities state
  • AppMsg - Crouton library - Support for Fragments?
crouton list of languages used
Other projects in Shell