Skip to main content
Help us improve Python packaging – donate today!

Python sandbox

Project Description

pysandbox is a Python sandbox. By default, untrusted code executed in the sandbox cannot modify the environment (write a file, use print or import a module). But you can configure the sandbox to choose exactly which features are allowed or not, eg. import sys module and read /etc/issue file.



Blocked Python functions (by default):

  • Deny access to the file system
  • Deny importing Python modules
  • Deny exiting Python
  • Deny access to stdin, stdout or stderr
  • Deny some builtins symbols like compile(), execfile() or KeyboardInterrupt
  • Deny execution of arbitrary bytecode (creation of arbitrary code object)

A timeout of 5 seconds if used by default. You can enable all of these features by setting the sandbox configuration.

Protection on the namespace:

  • Deny access to function closure, globals and code
  • Deny access to frame locals
  • Deny access to types subclasses
  • __builtins__ is read only
  • Deny access to dict methods able to modify a dict, eg. dict.__setitem__. But you can use “d[key] = value” and “del d[key]” instead


Use SandboxConfig class to configure your sandbox. Features are the most simple way to configure it.


To enable a feature, use SandboxConfig(‘feature1’, ‘feature2’, …) or config.enable(‘feature’). Available features:

  • “code”: compile() builtin, frame.f_locals and generator.gi_code
  • “debug_sandbox”: enable traceback of the sandbox itself
  • “exit”: sys.exit(), BaseException, KeyboardInterrupt, SystemExit, quit()
  • “future”: from __future__ import …
  • “help”:, use “import pydoc” outside the sandbox to use it
  • “interpreter”: give access to standard streams, enable traceback
  • “regex”: compile regex, match regex, search regex, etc. (re module)
  • “site”: allow to read the license file
  • “stdin”: sys.stdin, input() and raw_input()
  • “stdout”, “stderr”: sys.stdout and sys.stderr
  • “traceback”: next calls to allowModule() will add the module filename to the open() whitelist, so Python can display a traceback with the source code
  • “unicodedata”: unicodedata module, required for u’N{ATOM SYMBOL}’ syntax

CPython restricted mode

Use SandboxConfig(cpython_restricted=True) to enable CPython restricted mode. In this mode, reading a file and modify a class are blocked. Some attributes are hidden (eg. method.__self__), other are read only (eg. func.__doc__).

CPython restricted mode is disabled by default. The restricted mode is incompatible with SandboxConfig “traceback” feature and allowPath() method.

The restricted mode doesn’t exist in Python3 anymore, it was removed with bastion and rexec modules:

Other options

  • config.timeout: timeout in seconds. Use None to disable the timeout. Default timeout value is 5 seconds.
  • config.allowPath(path) allows to read a file from the specified path
  • config.allowModule(name, symbol1, symbol2, …) allows to import the specified module, but give only access to the specified symbols


With call() method:

from sandbox import Sandbox

def func(a, b):
    return a + b

sandbox = Sandbox()
print, 1, 2)

With execute() method:

from sandbox import Sandbox, SandboxConfig
sandbox = Sandbox(SandboxConfig('stdout'))
sandbox.execute('print("Code executed in the sandbox")')

execute() with a local variable:

from sandbox import Sandbox, SandboxConfig
sandbox = Sandbox(SandboxConfig('stdout'))
sandbox.execute('print(data)', locals={'data': [1, 2, 3]})    # ok
sandbox.execute('data.append(4)', locals={'data': [1, 2, 3]}) # error

Objects passed to .call() globals/locals and .execute() arguments are proxified: they are replaced by read-only views of the objects.


pysandbox is a sandbox for the Python namespace, not a sandbox between Python and the operating system. It doesn’t protect your system against Python security vulnerabilities: vulnerabilities in modules/functions available in your sandbox (depend on your sandbox configuration). By default, only few functions are exposed to the sandbox namespace which limits the attack surface.

pysandbox is unable to limit the memory of the sandbox process: you have to use your own protection.


pysanbox is tested on Python 2.5 and 2.6 on Debian Sid.

See TODO file for the complete status.

See also

Python-dev mailing list


Release history Release notifications

History Node


History Node


This version
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
pysandbox-1.0.3.tar.gz (24.6 kB) Copy SHA256 hash SHA256 Source None Sep 16, 2010

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page