jsii

library1.140.0pypypi✓ verified 24d ago

jsii is an open-source framework developed by AWS that enables code in any language (such as Python, Java, C#, and Go) to naturally interact with JavaScript classes authored in TypeScript. It is a core technology behind the AWS Cloud Development Kit (CDK), allowing polyglot libraries to be delivered from a single TypeScript codebase. The project is actively maintained by AWS, with frequent updates to the compiler, pacmak (bindings generator), and runtime libraries.

aws devops

pip install jsii

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JSII

jsii

awspythonv1.140.0

Install

2.2s avg

Import

281ms

Disk

21MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.140.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.288s · 23MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.2s · import 0.274s · 24MB

21MB installed

● package 21MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

jsii

✓ import jsii

The 'jsii' package itself is typically imported for decorators like @jsii.implements when authoring extensions to jsii-generated types. Application code consuming jsii-generated libraries imports directly from those libraries (e.g., 'from my_jsii_lib import MyClass').

implements

✓ from jsii import implements

Used as a decorator (@jsii.implements) to explicitly declare Python classes implementing jsii interfaces, avoiding metaclass conflicts.

The `jsii` library itself provides the runtime for generated modules. Python developers primarily interact with packages that have been *generated* by jsii (e.g., AWS CDK constructs). These generated packages depend on `jsii`. The example above illustrates how you would typically use a class from such a generated library.

import os from some_jsii_generated_lib import HelloJsii # NOTE: In a real scenario, 'some_jsii_generated_lib' would be a library # generated by jsii (e.g., AWS CDK, or your own jsii module) which has # 'jsii' as a dependency. The 'HelloJsii' class would be defined in TypeScript. # Example of using a class from a jsii-generated Python library try: # Assuming HelloJsii class and say_hello method are available # This code is illustrative; replace with actual generated lib usage. hello_instance = HelloJsii() message = hello_instance.say_hello("World") print(message) except ImportError: print("To run this, you need a jsii-generated library installed.") print("For example, 'pip install aws-cdk.core' and then use CDK classes.") except Exception as e: print(f"An error occurred: {e}")

jsii --version

Debug

Known issues

breakingThe `jsii-pacmak` tool and the Python libraries it generates now require a minimum Python version of 3.8. Previously, this was Python 3.7. It is recommended to upgrade to Python 3.11 or later.

fix

Ensure your Python environment is version 3.8 or higher. For best compatibility, use Python 3.11+.

affects: jsii-pacmak >= 1.86.0 (approx)

breakingAll `jsii` libraries and tools now require a minimum version of Node.js 18. This was previously Node.js 16. It is recommended to upgrade to Node.js 20 or later, as `jsii` modules rely on an embedded JavaScript VM.

fix

Upgrade your Node.js installation to version 18 or higher. For best compatibility, use Node.js 20+.

affects: jsii >= 1.127.0 (and related tools)

gotchaWhen implementing interfaces defined by `jsii` modules in Python, traditional multiple inheritance (e.g., `class MyNewClass(IJsiiInterface):`) will likely cause a metaclass conflict. This is due to `jsii`'s `JSIIMeta` metaclass.

fix

Use the `@jsii.implements(IJsiiInterface)` decorator to explicitly declare interface implementation. For example: `import jsii; @jsii.implements(IJsiiInterface) class MyNewClass():`

affects: All versions

gotchaWhen extending or implementing types from `jsii` modules, properties must always be implemented using Python's `@property` decorator to ensure the `jsii` runtime correctly processes access to them by the `jsii` kernel.

fix

Define properties using `@property` and `@<property_name>.setter` decorators.

affects: All versions

gotchaPassing Python `dict` literals in places where a `jsii` struct is expected might not always work consistently. This can lead to type-checking errors in the `jsii/kernel` module, incorrect translation of property keys (e.g., snake_case to camelCase), or properties being dropped entirely.

fix

Where possible, instantiate the `jsii` struct class explicitly instead of relying on implicit `dict` conversion. Consult the specific `jsii`-generated library's documentation for correct struct usage.

affects: All versions

gotchajsii modules, due to their reliance on an embedded JavaScript engine and marshalling costs, are best suited for development and build tools (like AWS CDK) rather than performance-sensitive or resource-constrained applications.

fix

Consider the performance implications for your specific use case. If high-performance is critical, native implementations might be more suitable.

affects: All versions

breakingThe required `jsii`-generated Python package was not found in the environment. This typically means the package was not installed or the Python environment path is incorrect.

fix

Ensure the `jsii`-generated Python package is correctly installed using pip (e.g., `pip install <package-name>`) and that the Python environment running the script has access to it.

affects: All versions

gotchaThe Python interpreter encountered a `ModuleNotFoundError`, indicating that the `jsii`-generated library or one of its dependencies could not be found in the current Python environment. This typically occurs when the library has not been installed, or the Python environment's paths are not correctly configured.

fix

Ensure the `jsii`-generated library is installed using `pip install <your-library-name>` or similar package management commands. Verify that the library's installation directory is included in your `PYTHONPATH` or that you are running your script within the activated virtual environment where the library is installed.

affects: All versions

Errors

Common errors & fixes

jsii.errors.JavaScriptError: Error: Cannot find module '@aws-cdk/cx-api'

This error, or similar 'Cannot find module' errors, occurs when the jsii runtime, often within an AWS CDK application, cannot locate a required JavaScript module, frequently due to version mismatches between CDK packages, missing dependencies, or improper bundling.

fix

Ensure all `aws-cdk-lib` packages (or specific CDK modules) and their dependencies are correctly installed and compatible. Run `npm install` in your TypeScript project and `pip install -r requirements.txt` (or equivalent) in your Python project. Consider upgrading to the latest stable versions of AWS CDK and `jsii` related packages.

TypeError: __new__() got an unexpected keyword argument 'jsii_type'

This error typically arises in Python when there is an incompatibility between the installed versions of `jsii` and `aws-cdk` or other jsii-generated libraries, where the Python bindings are expecting different arguments for the constructor.

fix

Upgrade your `aws-cdk` and `jsii` packages to compatible versions. Often, updating `pip install aws-cdk-lib jsii` (or `npm update` for the TypeScript source) resolves this. Ensure all CDK-related packages in your `requirements.txt` (for Python) or `package.json` (for TypeScript) are consistent.

ImportError: cannot import name '_Union' from 'typing'

This Python-specific error happens when an older version of `jsii` or its dependencies (like `cattrs`) tries to import an internal or removed symbol (`_Union`) from Python's standard `typing` module, often encountered with newer Python versions (e.g., Python 3.8+).

fix

Update your `jsii` and `cattrs` packages to their latest versions to ensure compatibility with your Python environment. For example, `pip install --upgrade jsii cattrs`. If the issue persists, ensure your Python version is officially supported by the specific `jsii` and CDK versions you are using.

error JSII4: Could not find "main" file: ...index.ts (or similar jsii compilation failed)

This indicates a failure during the jsii compilation process. It typically means that the `jsii` compiler cannot locate the main entry point file for your TypeScript project as specified in your `package.json` or `tsconfig.json` (e.g., `main` or `types` fields).

fix

Verify that your `package.json` file has a correct `main` and `types` field pointing to the actual main TypeScript file (e.g., `src/index.ts` or `lib/index.d.ts`). Ensure the file exists at the specified path. Check your `tsconfig.json` for proper `rootDir` and `outDir` settings.

Upgrade

Version history

1.140.0latest on PyPI · released Aug 24, 2026

Audit

Dependencies

jsii-pacmakoptionalUsed by authors to generate language bindings from jsii assemblies. It has a peer dependency on jsii-rosetta.

jsii-rosettarequiredPeer dependency of jsii-pacmak for sample code transliteration.

Agent activity

22 hits · last 30 days

node

Resources

githubhttps://github.com/aws/jsii ↗

packagehttps://pypi.org/project/jsii/ ↗

homepagehttps://aws.github.io/jsii ↗