Skip to main content

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

  • permissions contains CLI-style --allow-* strings in a list or tuple; any other type (including a mapping) raises ConfigurationError. An empty sequence requires allow_all_permissions=True; prompting is not exposed. -A/--allow-all grants all capabilities.
  • args and features are lists or tuples too, exposed through process.argv and the Deno unstable feature set respectively. features defaults to None, which keeps the runtime defaults.
  • capture_stdout, capture_stderr (both True by default) and max_capture_bytes apply to the *_with_output entry points. Truncation sets RunOutput.capture_truncated.
  • lang and base_dir apply to the in-memory entry points; base_dir must be an existing directory, otherwise ConfigurationError.
  • execution_deadline is a finite, non-negative number of seconds. A busy JavaScript run normally raises DenoTimeoutError when 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_bytes is an optional V8 old-generation constraint. It must be an integer (bool is rejected). Values below 8 MiB are rejected with ConfigurationError; 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 .tgz path has the same 1 GiB response-body cap. For a gzip response, the final four body bytes are checked as an ISIZE hint (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 when package.json is malformed or main escapes its directory. If main names a missing file, module loading fails with DenoRuntimeError.
  • 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 as DenoRuntimeError.
  • 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)

Source distribution for libdeno 0.3.9
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)

Table of built distributions (wheels) for libdeno 0.3.9
File Actions
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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Security 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.

Select from 6 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page