Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

a python library and cli tool that simplify chroot handling

Project Description


pychroot is a python library and cli tool that simplify chroot handling. Specifically, the library provides a Chroot context manager that enables more pythonic methods for running code in chroots while the pychroot utility works much like an extended chroot command in the terminal.


In its simplest form, the library can be used similar to the following:

from pychroot import Chroot

with Chroot('/path/to/chroot'):
    code that will be run
    inside the chroot

By default, this will bind mount the host’s /dev, /proc, and /sys filesystems into the chroot as well as the /etc/resolv.conf file (so DNS resolution works as expected in the chroot).

A simple chroot equivalent is also installed as pychroot. It can be used in a similar fashion to chroot; however, it also performs the bind mounts previously mentioned so the environment is usable. In addition, pychroot supports specifying custom bind mounts, for example:

pychroot -R /home/user ~/chroot

will recursively bind mount the user’s home directory at the same location inside the chroot directory in addition to the standard bind mounts. See pychroot’s help output for more options.

When running on a system with a recent kernel (Linux 3.8 and on) and user namespaces enabled pychroot can be run by a regular user. Currently pychroot just maps the current user to root in the chroot environment. This means that recursively chown-ing the chroot directory to the user running pychroot should essentially allow that user to act as root in the pychroot environment.

Implementation details

Namespaces are used by the context manager to isolate the chroot instance from the host system and to simplify the teardown phase for the environments. By default, new mount, UTS, IPC, and pid namespaces are used. In addition, if running as non-root, both user and network namespaces will be enabled as well so that the chrooting and mounting process will work without elevated permissions.

One quirk of note is that currently local variables are not propagated back from the chroot context to the main context due to the usage of separate processes running the contexts. This means that something similar to the following won’t work:

from pychroot import Chroot

with Chroot('/path/to/chroot'):
    answer = 42

In this case, a NameError exception will be raised unless the variable answer was previously defined. This will probably be fixed to some extent in a future release.


pychroot is quite Linux specific due to the use of namespaces via the snakeoil library which also require proper kernel support. Specifically, the following kernel config options are required to be enabled for full namespace support:



In a virtualenv or elsewhere via pip:

pip install pychroot

>From the repo manually:

python install


Please create an issue in the issue tracker.


Tests are handled via pytest, run via:


which is also integrated into, run via:

python test

Also, tests for all supported python versions can be run together or individually via:


Note that mock is required for tests when using python-2.7.

Release History

This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, Size & Hash SHA256 Hash Help File Type Python Version Upload Date
(23.3 kB) Copy SHA256 Hash SHA256
Wheel py2 Oct 4, 2017
(23.3 kB) Copy SHA256 Hash SHA256
Wheel py3 Oct 4, 2017
(32.9 kB) Copy SHA256 Hash SHA256
Source None Oct 4, 2017

Supported By

Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Google Google Cloud Servers DreamHost DreamHost Log Hosting