How to fix Error: [ERR_UNKNOWN_FILE_EXTENSION] Unknown file extension '.py' for module in Node.js

Node.jsINTERMEDIATEMEDIUM

Node.js throws ERR_UNKNOWN_FILE_EXTENSION when trying to import or execute files with unrecognized extensions. This commonly occurs with TypeScript files (.ts), Python files (.py), or other non-JavaScript file types that Node.js cannot natively process.

What this error means

This error occurs when Node.js encounters a file extension it doesn't know how to handle during module resolution or execution. By default, Node.js only recognizes JavaScript file extensions (.js, .mjs, .cjs) and JSON files (.json). When you try to import, require, or execute a file with any other extension—such as .ts (TypeScript), .py (Python), .jsx (React), or extensionless files—Node.js throws this error. The error is particularly common when: - Running TypeScript files directly without transpilation - Using ES modules (ESM) with "type": "module" in package.json - Attempting to execute files from other programming languages - Working with custom file extensions without proper loader configuration Node.js's module system requires explicit configuration through custom loaders or transpilers to handle non-standard file extensions. The error message typically includes the problematic extension and the file path where Node.js encountered the unknown extension.

How to fix "Error: [ERR_UNKNOWN_FILE_EXTENSION] Unknown file extension '.py' for module"

1Verify the file extension causing the error

Check the error message to identify which file extension is problematic:

bash

# The error will show something like:
Error: [ERR_UNKNOWN_FILE_EXTENSION] Unknown file extension '.ts' for /path/to/file.ts

If the extension is .ts, .tsx, or .jsx, you need a TypeScript/JSX transpiler. If it's .py, .java, or another language, you're trying to execute non-JavaScript code with Node.js.

2For TypeScript files: Use tsx instead of ts-node

Modern Node.js versions work better with tsx, which has better ESM support:

bash

# Install tsx
npm install --save-dev tsx

# Run TypeScript files directly
npx tsx src/index.ts

# Or add to package.json scripts
"scripts": {
  "dev": "tsx src/index.ts",
  "start": "node dist/index.js"
}

tsx provides seamless TypeScript execution without complex configuration and works reliably with Node.js 18+.

3For ts-node with ESM: Configure tsconfig.json properly

If you must use ts-node with "type": "module", configure tsconfig.json:

json

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "target": "ES2020"
  },
  "ts-node": {
    "esm": true,
    "experimentalSpecifierResolution": "node"
  }
}

Then run with the ESM loader:

bash

node --loader ts-node/esm src/index.ts

Note: experimentalSpecifierResolution is deprecated in newer Node.js versions.

4Remove "type": "module" if not needed

If you don't specifically need ES modules, removing "type": "module" from package.json can resolve the issue:

json

{
  "name": "your-project",
  // Remove or comment out this line:
  // "type": "module",
  "scripts": {
    "dev": "ts-node src/index.ts"
  }
}

Then ts-node will work in CommonJS mode, which has fewer compatibility issues.

5Compile TypeScript before running with Node.js

The most reliable approach is to transpile TypeScript to JavaScript first:

bash

# Compile TypeScript
npx tsc

# Run the compiled JavaScript
node dist/index.js

In package.json:

json

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "tsx src/index.ts"
  }
}

This separates development (tsx) from production (compiled JS), avoiding runtime transpilation issues.

6For custom file extensions: Use import assertions or loaders

If you need to import non-JavaScript files (.json, .graphql, etc.), use Node.js loaders:

javascript

// For JSON in ESM mode (Node.js 17.5+)
import config from './config.json' assert { type: 'json' };

// Or with import attributes (newer syntax)
import config from './config.json' with { type: 'json' };

For other file types, you'll need custom loaders or build-time transformations (webpack, vite, etc.).

How to fix Error: [ERR_UNKNOWN_FILE_EXTENSION] Unknown file extension '.py' for module in Node.js

What this error means

Typical symptoms

Common causes

How to fix "Error: [ERR_UNKNOWN_FILE_EXTENSION] Unknown file extension '.py' for module"

Advanced notes

Related errors

Official resources & further reading