Quickly spin up disposable Python sandboxes (virtualenv or Docker), install dependencies, execute code or scripts, capture output, and tear down—all with one simple API or CLI.
- Why sandboxr?
- Features
- Installation
- Quickstart
- Backend Details
- Advanced Examples
- Testing
- CI Integration
- Contributing
- License
When you need to:
- Test code snippets against different dependency versions
- Run untrusted or experimental code in isolation
- Provide "try-me" examples in documentation or tutorials
- Spin up throwaway environments for CI/CD smoke tests
…without polluting your global environment or managing virtualenvs by hand, sandboxr has you covered.
- Dual backends:
virtualenv— uses the standard libraryvenv+pip.docker— builds and runs ephemeral Docker images.
- One-line CLI: install, run code or file, tear down.
- Python API: full control in your scripts or tools.
- Automatic teardown: sandbox directories and images are cleaned up by default.
- Flexible installs: pre-install on creation and add packages later.
- Timeouts: guard runaway code with execution time limits.
- Cross-platform: macOS, Linux, Windows (Docker backend requires Docker).
pip install sandboxrNote: For editable installs (development), run:
pip install -e .# Run a one-off script in a virtualenv sandbox:
sandboxr \
--backend virtualenv \
--packages pandas,numpy \
--file demo_script.py
# Run inline code and keep the sandbox after execution:
sandboxr \
--backend docker \
--packages pytest \
--code "import pytest; print(pytest.__version__)" \
--keepOptions:
| Flag | Description |
|---|---|
| --backend | virtualenv or docker (required) |
| --packages | Comma-separated list of packages to pip-install before execution |
| --code | Inline Python code string (mutually exclusive with --file) |
| --file | Path to a .py file (mutually exclusive with --code) |
| --keep | Don't auto-teardown sandbox after execution (for debugging) |
from sandboxr import SandboxManager
# 1) Create a sandbox with numpy + requests
mgr = SandboxManager(backend="virtualenv", packages=["numpy>=1.24", "requests"])
sandbox = mgr.create()
# 2) Run some code
stdout, stderr, exit_code = sandbox.exec("""
import numpy as np
print(np.array([1,2,3]) * 2)
""")
print("OUT:", stdout)
print("ERR:", stderr)
print("CODE:", exit_code)
# 3) Install more packages on the fly
sandbox.install(["pandas"])
out2, err2, code2 = sandbox.exec("import pandas as pd; print(pd.__version__)")
# 4) Tear down when done
sandbox.teardown()Creation: uses venv.create() to build an isolated env
- install(packages: List[str]): pip-install inside the sandbox
- exec(code: str, timeout: int = 30): run code string, capture stdout/stderr
- exec_file(path: str, timeout: int = 30): execute a script file
- teardown(): delete the sandbox directory
from sandboxr.backends.virtualenv import VirtualenvSandboxCreation: writes a simple Dockerfile + docker build
- install(packages: List[str]): append RUN pip install layer, rebuild image
- exec(code: str, timeout: int = 30): docker run + capture output
- exec_file(path: str, timeout: int = 30): mount script into container, run
- teardown(): remove image + build context
from sandboxr.backends.docker import DockerSandboxTest multiple dependency versions
versions = ["1.5.0", "2.0.1"]
for ver in versions:
sb = SandboxManager("virtualenv", [f"pandas=={ver}"]).create()
out, _, _ = sb.exec("import pandas as pd; print(pd.__version__)")
print("Pandas", ver, "→", out.strip())
sb.teardown()Smoke-test a GitHub project
git clone https://github.com/psf/requests.git /tmp/requests-demo
sandboxr --backend virtualenv --packages pytest --code "import pytest; pytest.main(['/tmp/requests-demo'])"We use pytest for our own test suite:
# ensure Docker is running if you want to test the docker backend
PYTHONPATH=$(pwd) pytest -qHere's a minimal GitHub Actions snippet to run tests on push:
name: CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: 3.9
- name: Install dependencies
run: pip install -e . pytest
- name: Run tests
run: PYTHONPATH=$(pwd) pytest -q- Fork the repo
- Create a feature branch (git checkout -b feature/foo)
- Commit your changes (git commit -am 'Add foo')
- Push to the branch (git push origin feature/foo)
- Open a Pull Request
Please follow our Code of Conduct and Contributing Guidelines.
This project is licensed under the MIT License. See the LICENSE file for details.