pbuilder via pbuilder-scripts: A Short Howto

There are a myriad of ways to do cross-compiles and a smaller myriad that can do chrooted debian package builds. One of my favorite tools for this is pbuilder and I’d like to explain how (and why) I use it.

A pbuilder environment is a chrooted environment which can have a different distroseries or architecture than your host system. This is very useful, for example, when your laptop is running raring x64 and you need to build binaries for saucy armhf to run on Ubuntu Touch. Typically pbuilders are used to build debian packages, but they can also provide you a shell in which you can do non-package compilations. When you exit a pbuilder (typically) any packages you’ve installed or changes you’ve made are dropped. This makes it the perfect testing ground when building packages to ensure that you’ve defined all your dependencies correctly. pbuilder is also smart enough to install deps for you for package builds, which makes your life easier and also avoids polluting your development system with lots of random -dev packages. So if you’re curious, I recommend that you follow along below and try a pbuilder out, it’s pretty simple to get started.

Getting Setup

First install pbuilder and pbuilder-scripts. The scripts add-on really simplifies setup and usage and I highly recommend it. This guide makes heavy use of these scripts, although you can use pbuilder without them.

sudo apt-get install pbuilder pbuilder-scripts

Second, you need to setup your ~/.pbuilderrc file. This file defines a few things, mainly a set of extra default packages that your pbuilder will install and what directories are bind-mounted into your pbuilder. By default pbuilder scripts looks in ~/Projects, so make that directory at this point as well and set it in the .pbuilderrc file.

Add the following to .pbuilderrc, substitute your username for user:

BINDMOUNTS="${BINDMOUNTS} /home/user/Projects"
EXTRAPACKAGES="${EXTRAPACKAGES} pbuilder devscripts gnupg patchutils vim-tiny openssh-client"

I like having the openssh-client in my pbuilder so I can copy stuff out easier to target boxes, but it’s not strictly necessary. A full manpage for ~/.pbbuilderrc is also available to read about setting more advanced stuff.

Don’t forget to make the folder:
mkdir ~/Projects

Making your First Pbuilder

Now that you’re setup, it’s time to make your first pbuilder. You need to select a distroseries (saucy, raring, etc) and an architecture. I’m going to make one for the raring i386. To do this we use pcreate. I use a naming scheme here so that when I see the 10 builders I have, I can keep some sanity, I recommend you do the same, but if you want to call your pbuilder “bob” that’s fine too.

cd ~/Projects
pcreate -a i386 -d raring raring-i386

Running this will drop you into an editor. Here you can add extra sources, for example, if you need packages from a PPA. Any sources list you add here will be permanent anytime you use this pbuilder. If you have no idea what I mean by PPA, then just exit your editor here.

At this point pcreate will be downloading packages and setting up the chroot. This may take 10-30 minutes depending on your connection speed.

This is a good time to make coffee or play video games

This is a good time to make coffee or play video games

Using your pbuilder

pbuilders have two main use cases that I will cover here:

Package Builds

pbuilder for package builds is dead simple. If you place the package code inside ~/Projects/raring-x86, pbuilder will automagically guess the right pbuilder to use. Elsewhere and you’ll need to specify.

Aside: To avoid polluting the root folder, I generally lay the folders out like this:


Then I just do this

cd ~/Projects/raring-i386/project/project-0.52

This will unpack the pbuilder, install all the deps for “project” and then attempt to build it. It will exit the pbuilder (and repack it) whether it succeeds or fails. Any debs built will be up one level.

Other – via a Shell

The above method works great for building a package, but if you are building over and over to iterate on changes, it’s inefficient. This is because every time it needs to unpack and install dependencies (it is at least smart enough to cache the deps). In this case, it’s faster to drop into a shell and stay there after the build.

cd ~/Projects/raring-i386

This drops you into a shell inside the chroot, so you’ll need to manually install build-deps.

apt-get build-dep project

ptest also works great when you need to do non-package builds, for example, I build all my armhf test code in a pbuilder shell that I’ll leave open for weeks at a time.

Updating your pbuilder

Over time the packages in your pbuilder may get out of date. You can update it simply by running:

pupdate -p raring-i386

This is the equivalent of running apt-get upgrade on your system.


A few caveats for starting with pbuilder.

  • Ownership – files built by pbuilder will end up owned as root, if you want to manipulate them later, you’ll need to chown them back or deal with using sudo
  • Signing – unless you bind mount your key into your pbuilder you cannot sign packages in the pbuilder. I think the wiki page may cover other solutions.
  • Segfaults – I use pbuilders on top of qemu a lot so that I can build for ARM devices, however, it seems that the more complex the compile (perhaps the more memory intensive?) the more likely it is to segfault qemu, thereby killing the pbuilder. This happened to a colleague this week when trying to pbuild Unity8 for armhf. It’s happened to me in the past. The only solution I know for this issue is to build on real hardware.
  • Speed – For emulated builds, like armhf on top of x86_64 hardware (which I do all the time), pbuilds can be slow. Even for non-emulated builds, the pbuilder needs to uncompress itself and install deps every time. For this reason if you plan on doing multiple builds, I’d start with ptest.
  • Cleanup – When you tire of your pbuilder, you need to remove it from /var/cache/pbuilder. It also caches debs in here and some other goodies. You may need to clean those up manually depending on disk space constraints.


I’ve really only scratched the surface here on what you can do with pbuilder. Hopefully you can use it for package builds or non-native builds. The Ubuntu wiki page for pbuilder has lots more details, tips, and info. If you have any favorite tips, please leave them as a comment.

Tagged ,

6 thoughts on “pbuilder via pbuilder-scripts: A Short Howto

  1. Scott Sweeny says:

    For my scopes work the past couple of weeks I’ve had to build from a pbuilder shell to get binaries for the phone. Rather than install the build-deps (ubuntu-sdk, libmrss0-dev, probably some others) each time I start the shell I did the following:

    * Make a copy of my saucy-armhf pbuilder tarball (for clean builds later)
    * Run ptest –save
    * Install the build dependencies
    * Get building!

    The –save flag means that those packages are kept in the pbuilder and are ready to go the next time you start up the shell. Saves me ~20 minutes of package install time on every startup.

    If I need to make a clean package build later I can just replace the copy I made and I’m ready to go.

  2. Tong says:

    Is it possible to do multiple pbuilders with pbuilder-scripts?

    Reposting from https://answers.launchpad.net/ubuntu/+question/237841


    In Multiple pbuilders (https://wiki.ubuntu.com/PbuilderHowto#Multiple_pbuilders), it explains how to setup multiple pbuilders on the same machine.

    How to apply the principle to pbuilder-scripts?
    I see that pcreate has only a few limited options:

    Usage: pcreate [-c COMPONENTS] [-e “EXTRA PACKAGES”] [-s SOURCES]

    Is that possible?


    • Matt Fischer says:

      Sure. You just call pcreate as many times as you want. Each one gets it’s own folder in ~/Projects. I currently have the following pbuilders:

      • saucy-armhf
      • saucy-amd64
      • trusty-amd64

      I’ve had as many as 5 or 6 before. The only limiting factor is hard drive space.

  3. pbuilder-scripts is available to 12.04 LTS users through precise-backports: http://packages.ubuntu.com/precise-backports/devel/pbuilder-scripts

  4. Hey Mat,

    There’s a nice discussion page on pbuilder vs sbuild in askubuntu and it includes a blow-by-blow analysis in the second response. pbuilder wins by a slight point count.


Leave a Reply to Matt Fischer Cancel reply

Your email address will not be published. Required fields are marked *