Skip to main content

libdeno Python API

The Python distribution and Rust crate are versioned at 0.3.8. 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.8

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.8
File Size Uploaded Provenance Actions
libdeno-0.3.8.tar.gz 544.4 kB With provenance Details for libdeno-0.3.8.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for libdeno 0.3.8
File Actions
libdeno-0.3.8-cp39-abi3-win_amd64.whl CPython 3.9 abi3 Windows x86-64 Details for libdeno-0.3.8-cp39-abi3-win_amd64.whl
libdeno-0.3.8-cp39-abi3-manylinux_2_28_x86_64.whl CPython 3.9 abi3 Linux glibc 2.28+ x86-64 Details for libdeno-0.3.8-cp39-abi3-manylinux_2_28_x86_64.whl
libdeno-0.3.8-cp39-abi3-manylinux_2_28_aarch64.whl CPython 3.9 abi3 Linux glibc 2.28+ ARM64 Details for libdeno-0.3.8-cp39-abi3-manylinux_2_28_aarch64.whl
libdeno-0.3.8-cp39-abi3-macosx_11_0_arm64.whl CPython 3.9 abi3 macOS 11.0+ ARM64 Details for libdeno-0.3.8-cp39-abi3-macosx_11_0_arm64.whl
libdeno-0.3.8-cp39-abi3-macosx_10_12_x86_64.whl CPython 3.9 abi3 macOS 10.12+ x86-64 Details for libdeno-0.3.8-cp39-abi3-macosx_10_12_x86_64.whl

Total release size: 294.0 MB

Release files / libdeno-0.3.8.tar.gz

Download URL libdeno-0.3.8.tar.gz
Size 544.4 kB
Tags Source
SHA-256 checksum
How to use checksums
d032aec78061a503a1ba0069870a1fef662abfd454350039f71756caba5bfdb9
BLAKE2b-256 checksum
How to use checksums
8c62a9aded41f7adc11d53bcb8143e998e9bc6f3fb68cd388efe7de898467aff
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 Oct 28, 2026.

Transparency log

Release files / libdeno-0.3.8-cp39-abi3-win_amd64.whl

Download URL libdeno-0.3.8-cp39-abi3-win_amd64.whl
Size 54.8 MB
Tags CPython 3.9 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
6949b0e4396641ed3a2a1e0f978027c829b2735ec862a8f252a44b1a9078f413
BLAKE2b-256 checksum
How to use checksums
c5b658f20243110f8a7c748f94122ffa564732e000a94cb1057425fc86a51db6
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 Oct 28, 2026.

Transparency log

Release files / libdeno-0.3.8-cp39-abi3-manylinux_2_28_x86_64.whl

Download URL libdeno-0.3.8-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
99ba4bd6c3776356681692a30a831729950444c19253aa7a96a11e6e25df9d00
BLAKE2b-256 checksum
How to use checksums
9d913ef62d2c497e53546509273b7bf7f9b1997ce7a391136c7aa91d634fc50e
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 Oct 28, 2026.

Transparency log

Release files / libdeno-0.3.8-cp39-abi3-manylinux_2_28_aarch64.whl

Download URL libdeno-0.3.8-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
dc114b6a710437d0649a8475881a256e6ae574bd2c87286197c5da6fd18ce176
BLAKE2b-256 checksum
How to use checksums
12470aeef1e597c3870a1c9a4a36c571a9ed21bdbd6827fd98e6dc2eb7376396
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 Oct 28, 2026.

Transparency log

Release files / libdeno-0.3.8-cp39-abi3-macosx_11_0_arm64.whl

Download URL libdeno-0.3.8-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
6dc8e550556b454e5eef0c724930b9e7113d0c88000cb45e5f9a28cbc0ebd29d
BLAKE2b-256 checksum
How to use checksums
03eabe3c06a0e4da9de3a1805477e80e37cf1499b5c29ab2dd615912ded8210c
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 Oct 28, 2026.

Transparency log

Release files / libdeno-0.3.8-cp39-abi3-macosx_10_12_x86_64.whl

Download URL libdeno-0.3.8-cp39-abi3-macosx_10_12_x86_64.whl
Size 56.8 MB
Tags CPython 3.9 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
31250d720f11ff798b52414e792e81552f9d2dfe6f0dbc0a279c9cc3d7604faa
BLAKE2b-256 checksum
How to use checksums
f418538d35be56b6c30fe3eb4747e9abd810b7f6c414c27a27a7aaad531f558d
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 Oct 28, 2026.

Transparency log

Security for libdeno 0.3.8

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.8.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 Oct 28, 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