python2ts

1.4.3 verified Fri May 01 auth: no javascript

python2ts is an AST-based Python-to-TypeScript transpiler that converts Python code into clean, idiomatic TypeScript while preserving type annotations and semantics. The current stable version is 1.4.3 (January 2026), with active development and frequent releases (multiple per week). It supports a wide range of Python features including dataclasses, list/dict comprehensions, pattern matching, f-strings, async/await, decorators, context managers, generators, and standard library modules via the accompanying pythonlib runtime. Unlike other transpilers, python2ts produces readable, maintainable TypeScript output with full type preservation and has minimal runtime overhead, making it suitable for migrating large Python codebases to TypeScript. Requires Node >=22.0.0.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/python2ts/index.js not supported. ↓

cause Python2ts is ESM-only; using require() in a CommonJS context fails.

fix

Switch your project to ES modules or use dynamic import(): const python2ts = await import('python2ts');

error TypeError: python2ts.transpile is not a function ↓

cause Incorrect import: likely using default import instead of named import.

fix

Use import { transpile } from 'python2ts';

error Cannot find module 'pythonlib/builtins' or similar import in transpiled output. ↓

cause The 'pythonlib' runtime package is not installed.

fix

Run npm install pythonlib in the target project.

error SyntaxError: Unexpected token 'export' at ... ↓

cause The transpiled output uses ES module syntax but is loaded in a CommonJS context.

fix

Ensure the transpiled file is loaded as an ES module (e.g., use .mjs extension or { 'type': 'module' } in package.json).

Warnings

gotcha The TranspileOptions type is not exported directly from 'python2ts'; import from 'python2ts/types' instead. ↓

fix import type { TranspileOptions } from 'python2ts/types';

deprecated Using '--target es5' in CLI options is deprecated; ES2015+ is required. ↓

fix Remove --target flag or use a modern target like es2020.

gotcha Transpiled code depends on the 'pythonlib' package at runtime; it is not a standalone output. ↓

fix Ensure 'pythonlib' is installed in your project: npm install pythonlib

breaking In pythonlib v2.0.0, hashlib functions digest(), hexdigest(), pbkdf2Hmac(), scrypt(), and compareDigest() now return Promises and must be awaited. ↓

fix Update transpiled code to await these calls, e.g., const hash = await digest(data);

gotcha CLI output defaults to stdout; using -o with an existing file will overwrite without confirmation. ↓

fix Ensure the output file path is correct or that you have a backup.

breaking Version 1.0 dropped CommonJS support; the package is ESM-only. ↓

fix Use ES module imports (import/export) in your project. Update tsconfig to include 'module': 'ESNext'.

Install

npm install python2ts

yarn add python2ts

pnpm add python2ts

Imports

default
wrong
```
const python2ts = require('python2ts')
```
correct
```
import python2ts from 'python2ts'
```
python2ts is ESM-only starting from v1.0; CommonJS require will throw an error.

transpile

wrong

import transpile from 'python2ts'

correct

import { transpile } from 'python2ts'

transpile is a named export, not a default export.

TranspileOptions

wrong

import { TranspileOptions } from 'python2ts'

correct

import type { TranspileOptions } from 'python2ts/types'

Type imports should be from the 'types' subpath to avoid runtime overhead.

CLI
wrong
```
import * as python2ts from 'python2ts'; python2ts.cli()
```
correct
```
import { cli } from 'python2ts'
```
CLI is exported as a named function; namespace import works but direct named import is preferred.

Quickstart

Shows basic transpilation of a Python function with type hints and f-string to TypeScript.

import { transpile } from 'python2ts';

const pythonCode = `
def greet(name: str) -> str:
    return f"Hello, {name}!"
`;

try {
  const result = transpile(pythonCode, {
    filename: 'example.py',
    runtime: 'pythonlib', // default runtime path
  });
  console.log(result.code);
  // Output:
  // import { greet } from "pythonlib/builtins"
  // function greet(name: string): string {
  //   return `Hello, ${name}!`;
  // }
} catch (error) {
  console.error('Transpilation failed:', error.message);
}