python3 in a box is CPython 3.14 compiled to WebAssembly by
Pyodide. It runs scripts from the box's filesystem, reads stdin,
writes files back, and installs pure-Python packages with pip. It comes from the
lifo-pkg-python package, which is already there in lifo-sh and in the boxes on lifo.sh.
cd ~
printf 'name,score\nada,3\nlin,5\nkim,4\n' > scores.csv
python3 -c "import sys; print(sys.version.split()[0], sys.platform)"
python3 -c "import csv, statistics; rows = list(csv.DictReader(open('scores.csv'))); print('mean', statistics.mean(int(r['score']) for r in rows))"
echo '{"items": [1, 2, 3]}' | python3 -c "import json, sys; print(sum(json.load(sys.stdin)['items']))"The first python3 in a box downloads the interpreter: about 6 MB from the jsdelivr CDN in a
browser (cached by the browser after that), or the pyodide npm package in Node.js. It then
stays loaded for the box, so later runs start in milliseconds.
From your code
Register the commands on a box, then run Python like any other command:
import { Sandbox } from '@lifo-sh/core';
import python, { pip } from 'lifo-pkg-python'; // npm install lifo-pkg-python
const box = await Sandbox.create();
box.commands.register('python3', python);
box.commands.register('pip', pip);
await box.fs.writeFile('/home/user/primes.py', `
import sys
n = int(sys.argv[1])
primes = [p for p in range(2, n) if all(p % d for d in range(2, int(p ** 0.5) + 1))]
open('primes.txt', 'w').write(' '.join(map(str, primes)))
print(len(primes), 'primes below', n)
`);
const { stdout, exitCode } = await box.commands.run('python3 primes.py 100');
console.log(stdout, exitCode); // 25 primes below 100 0
console.log(await box.fs.readFile('/home/user/primes.txt')); // the file the script wroteRegister python too if scripts call it by that name. The package works the same in Node.js.
What it runs
python3 -c "<code>" [args] | a program from the command line |
python3 script.py [args] | a file, with sys.argv; its folder is on sys.path, so local modules import |
python3 -m <module> | a module as a script; python3 -m pip ... is pip |
python3 < prog.py, cat prog.py | python3 | a program on stdin |
python3 | an interactive prompt, on a terminal |
pip install <pkg> ..., pip install -r requirements.txt | packages from PyPI (see below) |
pip list, pip freeze, pip uninstall <pkg> |
Exit codes follow sys.exit(): sys.exit(3) exits 3, an uncaught exception prints its
traceback and exits 1. os.environ is the box's environment and os.getcwd() the shell's
directory.
Files
Python has its own in-memory filesystem, so the box's files are copied into it before each run and back out after:
- In: your home folder,
/tmp, the current directory and the script's folder, at the same paths. Unchanged files aren't copied again on the next run. - Out: whatever Python created, changed or deleted under those folders is written to the
box, so
python3 report.py && cat report.txtworks and the file explorer shows the result. - Left out:
node_modules,.git,__pycache__and files over 32 MB. Python doesn't write.pycfiles.
Paths outside those folders (/usr, /etc) aren't visible to Python. Run from the folder you
want it to see.
Packages
- Pure-Python packages install from PyPI with
pip install(it's micropip underneath):rich,attrs,cowsayand any other wheel with no compiled code. - Packages Pyodide builds, including numpy, pandas, scipy, scikit-learn, matplotlib and
pyyaml, load by themselves the first time a script imports them (a download
each, cached after).
pip install numpyworks too. - Installed packages last as long as the box: until the page reloads, or the Node.js process exits.
pip install cowsay
python3 -c "import cowsay; cowsay.cow('moo from a browser tab')"Limits
- No native extensions that Pyodide doesn't build. A wheel with compiled code for Linux or macOS won't install.
- No subprocesses or threads.
subprocess,os.forkandthreading.Thread.start()fail;multiprocessingdoesn't work. - Sockets. Raw sockets don't work. In a browser,
pyodide.http.pyfetchand pure-Python HTTP clients built on it can make requests (subject to CORS). - It shares the box's thread. A long computation blocks the page (or the Node.js event loop) until it ends, and Ctrl+C can't stop a busy loop.
input()on a terminal needs a browser with JavaScript Promise Integration (current Chrome). Piped input (echo 42 | python3 script.py) works everywhere.- One interpreter per box. Runs in the same box take turns; modules imported from your files are reloaded on each run, packages stay imported.
In a cloud box
python3 and pip work in cloud boxes the same way, with the box's
files. What differs:
- The interpreter loads again after every wake (a cloud box keeps files, not memory): about
2 seconds on the first
python3orpipafter the box boots or wakes, a few milliseconds after that. A box that has loaded Python uses roughly 60 to 190 MB more memory. - Installed packages don't survive a sleep.
pip installputs packages in the interpreter's memory, so install in the start command:--start "pip install -r requirements.txt && python3 job.py". - A Python script can't be the box's server: Python here has no sockets, so nothing listens
on a port. Serve with Node.js and call Python for the work, or run Python with
lifo cloud exec. pip install -vprints the package loader's messages and full errors, when an install fails.
PYODIDE_INDEX_URL in the box's environment loads Pyodide from another URL (a self-hosted
copy, for example), ending in /.