Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc

This article is still a Stub. You can help Gentoo-Wiki by expanding it.

Please improve it in any way that you see fit, and remove this notice {{Cleanup}} from the article. For tips on cleaning and formatting see Cleanup process



A typical Portage tree takes up around 600-700MB, this article describes how to reduce this to 30-40MB using a combination of SquashFS and UnionFS.

Please note that this guide assumes that you are using gentoo-sources or another kernel sources that has SquashFS.

Installing the Software

Kernel Configuration

If you are not using gentoo-sources, you may need to patch your kernel with the squashfs patch, which can be obtained from the squashfs website.

To be able to create and mount SquashFS files the following kernel options need to be enabled:

Linux Kernel Configuration: SquashFS
Device Drivers --->
  Block Devices --->
    <M> Loopback device support
File systems --->
  Miscellaneous Filesystems --->
    <M> SquashFS

(Note that these can also be compiled into the kernel instead of as modules)

Installing Necessary Tools

First, install the SquashFS tools:

emerge -av sys-fs/squashfs-tools

Next we need the unionfs kernel modules.

Patching your kernel for UnionFS

Note: The gentoo-sources kernel does not include UnionFS, if you are using a different kernel, unionfs may be included

Download the appropriate kernel patch from the unionfs home page. Copy it to the kernel directory and patch the kernel:

cd /usr/src/linux
cp <path to unionfs patch> .
gunzip unionfs-<version>.diff.gz
patch -p1 < unionfs-<version>.diff

Now unionfs will be in your kernel config:

Linux Kernel Configuration: UnionFS
File systems --->
  Layered Filesystems --->
    <M> UnionFS

(Note that these can also be compiled into the kernel instead of as modules)

Recompile your kernel:

make && make modules_install
cp arch/<architecture>/boot/bzImage /boot/<path to kernel>

UnionFS from Portage (deprecated)

Warning: This will only work if you have a kernel up to 2.6.18
emerge sys-fs/unionfs

Loading Modules

modprobe unionfs
modprobe squashfs
modprobe loop

Make sure to add unionfs, squashfs and loop to /etc/modules.autoload.d/kernel-2.6 or /etc/conf.d/modules if you have OpenRC/Baselayout-2. Obviously, the last two commands are not needed if you simply built the kernel options discussed earlier into the kernel.

Relocate Distfiles

/usr/portage will end up in a combined read-only image and a ramdisk, no good home for distfiles...

mkdir /var/portage
mv /usr/portage/distfiles /var/portage

put the following into /etc/make.conf:


Instead of moving /usr/portage/distfiles to /var/portage/distfiles, you could also simply create a new partition for /usr/portage/distfiles, if you have any space left on your harddisk. However, this will have certain implications in relation to the commands to create the squashed image. This article assumes you will move the distfiles directory, so if you are creating a new partition, please make sure not to follow this guide.

(If Installed) Relocate Layman

If Layman is installed, it needs its make.conf file moved outside the squashfs image.

mkdir /var/portage/layman
mv /usr/portage/local/layman/make.conf /var/portage/layman

In /etc/layman/layman.cfg change:

make_conf : %(storage)s/layman/make.conf


make_conf : /var/portage/layman/make.conf

In /etc/make.conf change:

source /usr/portage/local/layman/make.conf


source /var/portage/layman/make.conf

Creating the SquashFS Image

mksquashfs /usr/portage /var/portage/portage-current.sqfs -check_data
ln -sf /var/portage/portage-current.sqfs /var/portage/portage.sqfs

If everything worked, you can now remove your old, big, fat Portage Tree:

rm -rf /usr/portage/*

An initscript which takes care of updating and remounting the image

Put this into /etc/init.d/squash_portage:

File: /etc/init.d/squash_portage
# Copyright 1999-2006 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $
# /etc/init.d/squash_portage allows efficient compression of
# Gentoo portage arborescence
# It requires support for the loop device and squashfs enabled in the kernel,
# module autoloading is also *highly* recommended.
# sys-fs/squashfs and sys-fs/unionfs are necessary for read-write support.
# Author: Mathias Laurin <>
# 2006-11-28, v.0.1.5(4)

source /etc/make.globals
source /etc/make.conf

depend() {
   need localmount

start() {
   ebegin "Mounting read-only squashfs image"
   mount -rt squashfs -o loop,nodev,noexec $SQFS_CUR $PORTDIR
   eend $retval
   [ $retval -ne 0 ] && return $retval

   ebegin "Mounting read-write with unionfs"
   if [ ! $PORTAGE_RW ]
      einfo "  mounted in tmpfs (RAM)"
   [ -d $PORTAGE_RW ] || mkdir -p $PORTAGE_RW
   chmod 0750 $PORTAGE_RW
   chown portage:portage $PORTAGE_RW
   mount -t unionfs -o nodev,noexec,dirs=$PORTAGE_RW=rw:$PORTDIR=ro unionfs $PORTDIR
   eend $?

stop() {
   ebegin "Updating portage tree"
   [ ! $PORTAGE_RW ] && PORTAGE_RW="${DEF_RW}"
   if [ ! -z `ls -A $PORTAGE_RW | head -n1` ]
      einfo "  Syncing the tree"
      mv -f $SQFS_NEW $SQFS_OLD
      mksquashfs $PORTDIR $SQFS_NEW -no-duplicates 2>/dev/null
      ln -sf $SQFS_NEW $SQFS_CUR
      einfo "  Nothing to do"
   eend $retval

   ebegin "Unmounting the tree"
   umount -t unionfs  $PORTDIR
   umount -t squashfs $PORTDIR
   rm -rf $PORTAGE_RW
   eend 0

Don't forget to chmod 755 /etc/init.d/squash_portage.

Then put this into /etc/conf.d/squash_portage:

File: /etc/conf.d/squash_portage
# /etc/conf.d/squash_portage

# SQFS_DIRNAME points to the directory that will contain the sqfs
# images, recommended value is /var/tmp

# Leave PORTAGE_RW empty for use with tmpfs, a ram-based filesystem,
# This is recommended unless you are short of RAM

Mount your new Portage Tree

Let's put the init-script to work:

/etc/init.d/squash_portage start

...and don't forget to add it to the default runlevel:

rc-update add squash_portage default


Now, after a emerge --sync or eix-sync you can either

/etc/init.d/squash_portage restart

or just let it do it's work on shutdown and keep your updated packages in the ramdisk.


Retrieved from ""

Last modified: Sat, 17 May 2008 15:00:00 +0000 Hits: 16,189