Skip to main content

Launch Python environments quickly, using Linux's clone() syscall.

Project description

Clone sandboxed Python processes quickly and securely.


Documentation is available at


Create a pyspawner.Client that imports the “common” Python imports your sandboxed code will run. (These import statements aren’t sandboxed, so be sure you trust the Python modules.)

Then call pyspawner.Client.spawn_child() each time you want to create a new child. It will invoke the pyspawner’s child_main function with the given arguments.

Here’s pseudo-code for invoking the pyspawner part:

import pyspawner

# pyspawner.Client() is slow; ideally, you'll just call it during startup.
with pyspawner.Client(
    environment={"LC_ALL": "C.UTF-8"},
    preload_imports=["pandas"],  # put all your slow imports here
) as cloner:
    # cloner.spawn_child() is fast; call it as many times as you like.
    child_process: pyspawner.ChildProcess = cloner.spawn_child(
        args=["arg1", "arg2"],  # List of picklable Python objects

    # child_process has .pid, .stdin, .stdout, .stderr.
    # Read from its stdout and stderr, and then wait for it.

For each child, read from stdout and stderr until end-of-file; then wait() for the process to exit. Reading from two pipes at once is a standard exercise in UNIX, so the minutae are left as an exercise. A safe approach:

  1. Register both stdout and stderr in a selectors.DefaultSelector
  2. loop, calling and reading from whichever file descriptors have data. Unregister whichever file descriptors reach EOF; and read but _ignore_ data past a predetermined buffer size. Kill the child process if this is taking too long. (Keep reading after killing the child to avoid deadlock.)
  3. Wait for the child process (using os.waitpid()) to clean up its system resources.

Setting up your environment

Your system must have installed.

Pyspawner relies on Linux’s clone() system call to create child-process containers. If you’re using pyspawner from a Docker container, subcontainer are disabled by default. Run Docker with --seccomp-opt=/path/to/pyspawner/docker/pyspawner-seccomp-profile.json to allow creating subcontainers.

By default, sandboxed children cannot access the Internet. If you want to enable networking for child processes, ensure your process has the CAP_NET_ADMIN capability. (docker run --cap-add NET_ADMIN ...). Also, you’ll need to configure NAT in the parent-process environment … which is beyond the scope of this README. Finally, you may want to supply a chroot_dir to give child processes a custom /etc/resolv.conf.

Ideally, sandboxed children would not be able to write anywhere on the main filesystem. Unfortunately, the umount() and pivot_root() system calls are restricted in many environments. As a placeholder, you’re encouraged to supply a chroot_dir to provide an environment for your sandboxed child code. chroot_dir must be in a separate filesystem from the root filesystem. (In the future, when the Linux container ecosystem evolves enough, chroot_dir will make children unmount the root filesystem.) Again, chroot is beyond the scope of this README.


The test suite depends on Docker. (Security tests involve temporary files outside of temporary directories, iptables rules and setuid-0 files.)

Run ./ to test.

To add or fix features:

  1. Write a test in tests/ that breaks.
  2. Write code in pyspawner/ that makes the test pass.
  3. Submit a pull request.


  1. Run ./ and sphinx-build docs docs/build to check for errors.
  2. Write a new version in pyspawner/ Use semver – e.g., 1.2.3.
  3. Write a CHANGELOG.rst entry.
  4. git commit
  5. git tag VERSION (use semver with a v – e.g., v1.2.3)
  6. git push --tags && git push
  7. python3 ./ sdist
  8. twine upload dist/*



Project details

Download files

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

Files for pyspawner, version 0.9.2
Filename, size File type Python version Upload date Hashes
Filename, size pyspawner-0.9.2.tar.gz (24.0 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page