componentize-py

This is a tool to convert a Python application to a WebAssembly component. It takes the following as input:

a WIT file or directory
the name of a WIT world defined in the above file or directory
the name of a Python module which targets said world
a list of directories in which to find the Python module and its dependencies

The output is a component which may be run using e.g. wasmtime.

Getting Started

First, install Python 3.10 or later and pip if you don't already have them. Then, install componentize-py:

pip install componentize-py

Next, create or download the WIT world you'd like to target, e.g.:

cat >hello.wit <<EOF
package example:hello;
world hello {
  export hello: func() -> string;
}
EOF

If you're using an IDE or just want to examine the bindings produced for the WIT world, you can generate them using the bindings subcommand:

componentize-py -d hello.wit -w hello bindings hello_guest

Then, use the hello module produced by the command above to write your app:

cat >app.py <<EOF
import wit_world
class WitWorld(wit_world.WitWorld):
    def hello(self) -> str:
        return "Hello, World!"
EOF

And finally generate the component:

componentize-py -d hello.wit -w hello componentize --stub-wasi app -o app.wasm

To test it, you can install wasmtime-py and use it to generate host-side bindings for the component:

[!NOTE] Due to compatibility issues with wasmtime-py versions beyond 38.x, this example requires version 38.0.0 or earlier: pip install "wasmtime==38.0.0"

pip install wasmtime==38.0.0
python3 -m wasmtime.bindgen app.wasm --out-dir hello_host

Now we can write a simple host app using those bindings:

cat >host.py <<EOF
from hello_host import Root
from wasmtime import Config, Engine, Store

config = Config()
config.cache = True
engine = Engine(config)
store = Store(engine)
hello = Root(store)
print(f"component says: {hello.hello(store)}")
EOF

And finally run it:

 $ python3 host.py
component says: Hello, World!

See the examples directories for more examples, including various ways to run the components you've created.

Known Limitations

Currently, the application can only import dependencies during build time, which means any imports used at runtime must be resolved at the top level of the application module. For example, if x is a module with a submodule named y the following may not work:

import x

class Hello(hello.Hello):
    def hello(self) -> str:
        return x.y.foo()

That's because importing x does not necessarily resolve y. This can be addressed by modifying the code to import y at the top level of the file:

from x import y

class Hello(hello.Hello):
    def hello(self) -> str:
        return y.foo()

This limitation is being tracked as issue #23.

See the issue tracker for other known issues.

Contributing

See CONTRIBUTING.md for details on how to contribute to the project and build it from source.

Release files for componentize-py 0.25.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for componentize-py 0.25.1
File	Size	Uploaded
componentize_py-0.25.1.tar.gz	192.2 kB	Sep 12, 2026	Details

Built distributions (wheels)

Table of built distributions (wheels) for componentize-py 0.25.1
File	Interpreter	ABI	Platform	Reset
componentize_py-0.25.1-cp39-abi3-win_amd64.whl 15.3 MB Sep 12, 2026	CPython 3.9	abi3	Windows x86-64	Details
componentize_py-0.25.1-cp39-abi3-manylinux_2_28_x86_64.whl 17.1 MB Sep 12, 2026	CPython 3.9	abi3	Linux glibc 2.28+ x86-64	Details
componentize_py-0.25.1-cp39-abi3-manylinux_2_28_aarch64.whl 17.1 MB Sep 12, 2026	CPython 3.9	abi3	Linux glibc 2.28+ ARM64	Details
componentize_py-0.25.1-cp39-abi3-macosx_11_0_arm64.whl 15.4 MB Sep 12, 2026	CPython 3.9	abi3	macOS 11.0+ ARM64	Details
componentize_py-0.25.1-cp39-abi3-macosx_10_12_x86_64.whl 16.1 MB Sep 12, 2026	CPython 3.9	abi3	macOS 10.12+ x86-64	Details

Total release size: 81.2 MB

Release files / componentize_py-0.25.1.tar.gz

Download URL	componentize_py-0.25.1.tar.gz
Size	192.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`e4087e916b06171303f803c8ffdd5f177e2422e87d9bed6ffe55cc41b2248aa8`
BLAKE2b-256 checksum How to use checksums	`773dc769bac866429f36a6d52451fb2980d5e8784efb1d265fb85eaaceb3c285`
Upload date	Sep 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.9.6`

Release files / componentize_py-0.25.1-cp39-abi3-win_amd64.whl

Download URL	componentize_py-0.25.1-cp39-abi3-win_amd64.whl
Size	15.3 MB
Tags	CPython 3.9 Windows x86-64 abi3
SHA-256 checksum How to use checksums	`c7fd552fb0849858b0c1e8981543ed5dff4b0cc1597a8ea0bc26a495786dc0c6`
BLAKE2b-256 checksum How to use checksums	`4b605b08715534795d84feec8ec8ae50599681ea1199ee7b300ad072fdcd24af`
Upload date	Sep 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.9.6`

Release files / componentize_py-0.25.1-cp39-abi3-manylinux_2_28_x86_64.whl

Download URL	componentize_py-0.25.1-cp39-abi3-manylinux_2_28_x86_64.whl
Size	17.1 MB
Tags	CPython 3.9 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum How to use checksums	`8623cd8cab8453cb0cd8bf03f3c7103420d06f2f3d360186a280a70a1ca5e89f`
BLAKE2b-256 checksum How to use checksums	`edc6ad1431751ff1969a132323f6e2797ec38ccdf9d0a53aabb45d79221092a4`
Upload date	Sep 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.9.6`

Release files / componentize_py-0.25.1-cp39-abi3-manylinux_2_28_aarch64.whl

Download URL	componentize_py-0.25.1-cp39-abi3-manylinux_2_28_aarch64.whl
Size	17.1 MB
Tags	CPython 3.9 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum How to use checksums	`7b6a87c520358166843af0daa86d2312d7af4cbcbbf1e598951085cf7f2991ca`
BLAKE2b-256 checksum How to use checksums	`566624a9671f1d9c608e53a8d5ae4873d1fc480f0603488a2f46132e70cc6839`
Upload date	Sep 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.9.6`

Release files / componentize_py-0.25.1-cp39-abi3-macosx_11_0_arm64.whl

Download URL	componentize_py-0.25.1-cp39-abi3-macosx_11_0_arm64.whl
Size	15.4 MB
Tags	CPython 3.9 abi3 macOS 11.0+ ARM64
SHA-256 checksum How to use checksums	`a556991534cc496207a9d2ca733c4b0f17ed38ef56a8d6b5f1847fdf1225dd1b`
BLAKE2b-256 checksum How to use checksums	`4b9cf444240899a9b43c60b808d0ece5dff8f3dc6831aa119a1d8eb28d952bad`
Upload date	Sep 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.9.6`

Release files / componentize_py-0.25.1-cp39-abi3-macosx_10_12_x86_64.whl

Download URL	componentize_py-0.25.1-cp39-abi3-macosx_10_12_x86_64.whl
Size	16.1 MB
Tags	CPython 3.9 abi3 macOS 10.12+ x86-64
SHA-256 checksum How to use checksums	`65fbc4a94df1de8acf7da50a1f5ed1711230188844e53e6332d99029be4e0afa`
BLAKE2b-256 checksum How to use checksums	`a1fcea8ac30a3de452626e32c051a38f548e9f7863cd10c35705396e257ac029`
Upload date	Sep 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.9.6`