libdeno Python API
The Python distribution and Rust crate are versioned at 0.3.9. The Python
API is alpha and provides synchronous access to the runtime:
import libdeno
exit_code = libdeno.run(
"entry.js",
permissions=("--allow-read=.",),
args=("app-arg",),
)
runtime = libdeno.Runtime(cwd=None)
exit_code = runtime.run("entry.js", allow_all_permissions=True)
run() and Runtime.run() block until the script and its event loop finish,
return an exit code, and release the GIL while Rust runs. Runtime reuses the
resolver stack; permissions, module graphs, and isolates remain per run.
entry and cwd accept str, bytes, and os.PathLike values, including
non-ASCII paths. cwd=None (or an omitted cwd) means the process current
directory. For Runtime, that directory is fixed when the object is created;
the process cwd is never changed. Options after entry are keyword-only.
run_with_output() captures the script's stdout/stderr into a RunOutput
(exit_code, stdout, stderr, capture_truncated). Both streams are
captured by default; disable one with capture_stdout=False /
capture_stderr=False, and bound each with max_capture_bytes. Capture
redirects process-global file descriptors, so a captured run is exclusive and
a concurrent run raises ConfigurationError; it is not supported on Windows.
run_source() and run_source_with_output() run code held in memory. code
is str (encoded as UTF-8), bytes, or bytearray; lang is
SourceLang.JavaScript, SourceLang.TypeScript, or the strings
"javascript"/"typescript"; base_dir is the existing directory the virtual
entry lives in, so relative imports resolve against it.
output = libdeno.run_source_with_output(
"const answer: number = 42;\nconsole.log(answer);",
lang=libdeno.SourceLang.TypeScript,
allow_all_permissions=True,
)
print(output.stdout)
The Python binding does not expose async APIs, subprocess helpers, permission hooks, or native addons. Script-level Deno APIs still follow the Rust runtime's permission model.
Async callers should wrap the blocking entry points:
await asyncio.to_thread(libdeno.run, "entry.js", allow_all_permissions=True).
The GIL is already released for the whole run, so this only moves the call off
the event loop thread.
Options and limits
permissionscontains CLI-style--allow-*strings in a list or tuple; any other type (including a mapping) raisesConfigurationError. An empty sequence requiresallow_all_permissions=True; prompting is not exposed.-A/--allow-allgrants all capabilities.argsandfeaturesare lists or tuples too, exposed throughprocess.argvand the Deno unstable feature set respectively.featuresdefaults toNone, which keeps the runtime defaults.capture_stdout,capture_stderr(bothTrueby default) andmax_capture_bytesapply to the*_with_outputentry points. Truncation setsRunOutput.capture_truncated.langandbase_dirapply to the in-memory entry points;base_dirmust be an existing directory, otherwiseConfigurationError.execution_deadlineis a finite, non-negative number of seconds. A busy JavaScript run normally raisesDenoTimeoutErrorwhen the deadline fires, but this is best effort: blocking system calls, native code, and blocked permission paths can make a run exceed it.max_heap_bytesis an optional V8 old-generation constraint. It must be an integer (boolis rejected). Values below 8 MiB are rejected withConfigurationError; the value does not cap native allocations, external memory, host memory, RSS, CPU, or child processes. It is not an OS/process isolation boundary.- HTTP body limits apply to reqwest-returned, transport-decoded response-body
bytes, not wire bytes; upstream decoding may allocate before the limit is
checked. The explicit npm
.tgzpath has the same 1 GiB response-body cap. For a gzip response, the final four body bytes are checked as anISIZEhint (the final member's size modulo 2^32); this threshold is not a decompressed- output budget and does not identify the first consumed member or total extraction. Fallback extraction has no hard output budget, so this is not a decompression or RSS cap.
Exceptions
The facade exports LibdenoError and these subclasses:
EntryError— the entry path does not exist or entry resolution fails, such as whenpackage.jsonis malformed ormainescapes its directory. Ifmainnames a missing file, module loading fails withDenoRuntimeError.DenoPermissionError— invalid permission flags or denials carrying typed Rust permission provenance. JavaScript exception names/classes/causes are not trusted as denial evidence; a JS failure, including a denial whose typed provenance was lost, is reported asDenoRuntimeError.ConfigurationError— options cannot form a valid run, including empty permissions without an explicit opt-in, invalid deadlines, or an undersized heap value.DenoRuntimeError— runtime startup or JavaScript failure.DenoIOError— host filesystem/I/O failure.DenoTimeoutError— the runtime reported an execution deadline timeout.
Install from the next source release
The next libdeno release will include an sdist. After that release is published, install it with:
python -m pip install --no-binary=libdeno "libdeno==<next-release-version>"
Building requires Rust 1.95 or newer, a C/C++ toolchain, and libclang (for
example, libclang-dev on Debian/Ubuntu). Cargo and the V8 build download
platform-specific dependencies; an sdist does not provide cross-compilation.
The tested release wheel targets are Linux x86_64/aarch64, macOS x86_64/arm64,
and Windows x86_64.
Build and install from a local source archive
Use a virtual environment rather than installing build tools globally:
cd python
python -m venv .venv
. .venv/bin/activate
python -m pip install "maturin==1.13.3"
maturin sdist --out target/sdist
python -m pip install target/sdist/*.tar.gz
cd ..
python -m unittest discover -s python/tests -p 'test_*.py'
The sdist contains the Rust crates and build support needed to compile outside
the checkout. For a local prebuilt wheel instead, run ./build-wheel.sh from
python/ and install a wheel from target/wheels/. Wheels use the Python 3.9
stable ABI and target Python 3.9+. The wheel build script clears
RUSTC_WRAPPER, resolves the active compiler dynamically, and uses Cargo's
locked dependency resolution; it requires Bash.
To build and install that wheel in a virtual environment:
cd python
python -m venv .venv
. .venv/bin/activate
python -m pip install "maturin==1.11.5"
./build-wheel.sh
python -m pip install target/wheels/*.whl
cd ..
python -m unittest discover -s python/tests -p 'test_*.py'
Run the stdlib test suite after installing the wheel from the repository root,
so the source package does not shadow the installed package. Keep the same
virtual environment activated so python refers to its interpreter.
Limitations
- Prompting and permission hooks.
- Async APIs (use
asyncio.to_thread) and subprocess execution. - Python-facing permission/options objects beyond the keyword arguments above.
- Native addons.
- The Python API remains alpha and may change.
Metadata
Release files for libdeno 0.3.9
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| libdeno-0.3.9.tar.gz | 640.8 kB | With provenance | Details for libdeno-0.3.9.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| libdeno-0.3.9-cp39-abi3-win_amd64.whl | CPython 3.9 | abi3 | Windows x86-64 | Details for libdeno-0.3.9-cp39-abi3-win_amd64.whl |
| libdeno-0.3.9-cp39-abi3-manylinux_2_28_x86_64.whl | CPython 3.9 | abi3 | Linux glibc 2.28+ x86-64 | Details for libdeno-0.3.9-cp39-abi3-manylinux_2_28_x86_64.whl |
| libdeno-0.3.9-cp39-abi3-manylinux_2_28_aarch64.whl | CPython 3.9 | abi3 | Linux glibc 2.28+ ARM64 | Details for libdeno-0.3.9-cp39-abi3-manylinux_2_28_aarch64.whl |
| libdeno-0.3.9-cp39-abi3-macosx_11_0_arm64.whl | CPython 3.9 | abi3 | macOS 11.0+ ARM64 | Details for libdeno-0.3.9-cp39-abi3-macosx_11_0_arm64.whl |
| libdeno-0.3.9-cp39-abi3-macosx_10_12_x86_64.whl | CPython 3.9 | abi3 | macOS 10.12+ x86-64 | Details for libdeno-0.3.9-cp39-abi3-macosx_10_12_x86_64.whl |
Total release size: 294.1 MB
Release files / libdeno-0.3.9.tar.gz
| Download URL | libdeno-0.3.9.tar.gz |
|---|---|
| Size | 640.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b5e0c014adc9c187a34518a6796ba4e4973bd4866f205e396d1a5c206e0e97b1
|
|
BLAKE2b-256 checksum How to use checksums |
974f659dfdfe2eced89ba47c699f19d1f949540038915ff7d6e4e14464bec9f8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.
Transparency logRelease files / libdeno-0.3.9-cp39-abi3-win_amd64.whl
| Download URL | libdeno-0.3.9-cp39-abi3-win_amd64.whl |
|---|---|
| Size | 54.8 MB |
| Tags | CPython 3.9 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
f7e78633dd714699d96212e3d9059cb2ee3fe7992b9875d9c779cb324d030a2b
|
|
BLAKE2b-256 checksum How to use checksums |
d847aa06787e4a9ade8b5d5342fa95d0756105891fd055273ecab6e299cc5917
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.
Transparency logRelease files / libdeno-0.3.9-cp39-abi3-manylinux_2_28_x86_64.whl
| Download URL | libdeno-0.3.9-cp39-abi3-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 62.1 MB |
| Tags | CPython 3.9 Linux glibc 2.28+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
a33d02084010955ecc6abcc523ea11561b653df60834b00de29769f2b942a232
|
|
BLAKE2b-256 checksum How to use checksums |
a2d4bdf56942fc170ade3a26495bfd8a27f5e45e6cb97358a2395be1d640a802
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.
Transparency logRelease files / libdeno-0.3.9-cp39-abi3-manylinux_2_28_aarch64.whl
| Download URL | libdeno-0.3.9-cp39-abi3-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 65.7 MB |
| Tags | CPython 3.9 Linux glibc 2.28+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
bea0ad76ae8b4fa168b86da32dac7cdfd6477c760ad26daee891f345bf2dc8ae
|
|
BLAKE2b-256 checksum How to use checksums |
7f5f784a91e6fe4793d4de23a493dc7c4bb8bd467c9a76629745224bb88e4658
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.
Transparency logRelease files / libdeno-0.3.9-cp39-abi3-macosx_11_0_arm64.whl
| Download URL | libdeno-0.3.9-cp39-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 54.2 MB |
| Tags | CPython 3.9 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
4ce152dd18538d53cd98af7490f6a9e98ad16e6e4eb85e2f596fdde75b7a0c5b
|
|
BLAKE2b-256 checksum How to use checksums |
3fb8f4e0f80d6133ee99035959c0f9018de85e4be7f63bdafc69686b7390f911
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.
Transparency logRelease files / libdeno-0.3.9-cp39-abi3-macosx_10_12_x86_64.whl
| Download URL | libdeno-0.3.9-cp39-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 56.7 MB |
| Tags | CPython 3.9 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
373fb21b3502ade37715995df9fa73958f62c14d11eb1be3214150bdc86ac5cf
|
|
BLAKE2b-256 checksum How to use checksums |
cbbadf8fd4e13cca56415ecb5ad0ca07a8442ff4583cc6f992980889c06207f0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.
Transparency logSecurity for libdeno 0.3.9
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 6 files in this release have been uploaded with provenance metadata.
Attestation for libdeno-0.3.9.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.