edx-codejail

4.1.0 verified Mon Apr 27 auth: no python

CodeJail manages execution of untrusted code in secure sandboxes. It is designed primarily for Python execution, but can be used for other languages as well. The current version is 4.1.0, released May 2025. Release cadence is irregular, approximately 2-3 minor versions per year.

pip install edx-codejail

Common errors

error ImportError: cannot import name 'CodeJail' from 'codejail' ↓

cause CodeJail is in codejail.jail, not top-level codejail.

fix

Use: from codejail.jail import CodeJail

error codejail.safe_exec: unsafe execution is not allowed ↓

cause Since v4.0.0, unsafe execution is opt-in. The safe_exec function requires explicit permission.

fix

Either use jail.run() with appropriate configuration or set the environment variable CODEJAIL_UNSAFE=1 (not recommended for production).

error FileNotFoundError: /usr/bin/python3 not found ↓

cause The python_path specified does not exist or is not executable.

fix

Verify the Python interpreter path on your system (which python3) and pass the correct path.

error OSError: [Errno 13] Permission denied: '/usr/bin/python3' ↓

cause The user running the jail does not have execute permission on the Python interpreter.

fix

Run the application as a user with appropriate permissions, or adjust file permissions.

Warnings

breaking In v4.0.0, 'unsafe execution' now requires explicit opt-in via calling code rather than being allowed by default. Code that relied on the old behavior will raise an error. ↓

fix Update code to handle cases where execution is blocked, or explicitly configure the jail to allow unsafe operations if needed.

gotcha CodeJail requires root or specific user privileges to set up AppArmor profiles. Running without proper system configuration will cause silent failures. ↓

fix Ensure AppArmor is installed and the codejail profile is loaded. Run as root or use appropriate sudo.

gotcha The safe_exec function does not capture stdout/stderr; it returns a dictionary with 'status', 'stderr', etc. New users often expect print() output to appear. ↓

fix Use jail.run() for more control or parse the returned dict.

deprecated Using 'sys_packages' argument to CodeJail is deprecated. Use 'python_path' instead. ↓

fix Replace sys_packages with python_path in CodeJail constructor.

Imports

CodeJail
wrong
```
from codejail import CodeJail
```
correct
```
from codejail.jail import CodeJail
```
importing from top-level breaks because CodeJail is defined in codejail.jail

is_safe

wrong

from codejail import is_safe

correct

from codejail.safe_exec import is_safe

is_safe is in codejail.safe_exec, not top-level

safe_exec

wrong

from codejail.jail import safe_exec

correct

from codejail.safe_exec import safe_exec

safe_exec function is in codejail.safe_exec module

Quickstart

Basic usage: configure a jail and execute untrusted code safely.

from codejail.jail import CodeJail
from codejail.safe_exec import safe_exec

# Configure a Python jail (requires proper system setup)
jail = CodeJail('python', user='sandbox', sys_packages=['/usr/bin/python3'])

# Use safe_exec for quick sandboxed execution
result = safe_exec("print(1+1)", globals=globals(), python_path='/usr/bin/python3')
print(result)