How to fix ts-node: TypeScript version mismatch in TypeScript

TypeScriptINTERMEDIATEMEDIUMUpdated Dec 11, 2025· 139 views

This error occurs when the TypeScript version used by ts-node doesn't match the version in your project's dependencies. The mismatch prevents ts-node from properly compiling and executing TypeScript code, requiring version alignment or configuration adjustments.

Quick fix

Fixes ts-node: TypeScript version mismatch

# Check global TypeScript version
tsc --version

# Check local TypeScript version (from node_modules)
npx tsc --version

# Check ts-node version
npx ts-node --version
  1. Check your TypeScript versions
  2. Ensure TypeScript is a local dependency
  3. Reinstall dependencies to fix version conflicts
  4. Configure ts-node to use project TypeScript
typescript — error
# Check global TypeScript version
tsc --version
# Check local TypeScript version (from node_modules)
npx tsc --version
# Check ts-node version
npx ts-node --version
ts-node: TypeScript version mismatch

What this error means

ts-node is a TypeScript execution engine that compiles and runs TypeScript code directly without pre-compilation. It requires access to the TypeScript compiler (tsc) to transform TypeScript into JavaScript at runtime. The "TypeScript version mismatch" error happens when ts-node detects that the TypeScript version it's using internally differs from the version specified in your project's `package.json` or `node_modules`. This mismatch can cause: - Incompatible TypeScript language features - Different compiler behavior - Missing or mismatched type definitions - Compilation failures ts-node performs this version check to ensure consistent behavior between development (ts-node) and production (tsc compilation). The error typically appears when you have multiple TypeScript installations or when global and local TypeScript versions conflict.

Typical symptoms

  • Error appears when running TypeScript files with ts-node
  • Command fails with 'ts-node: TypeScript version mismatch' message
  • npm scripts using ts-node fail to execute
  • Development server (like nodemon with ts-node) crashes on startup
  • Different behavior between ts-node and tsc compilation
  • Type errors appear in ts-node but not in tsc

Common causes

  1. Global TypeScript installation conflicts with local project version
  2. Multiple TypeScript versions in node_modules (e.g., from different packages)
  3. ts-node installed globally but TypeScript installed locally (or vice versa)
  4. Yarn or npm hoisting creates version conflicts in monorepos
  5. Package manager lockfile (package-lock.json, yarn.lock) has inconsistent versions
  6. ts-node configuration specifies a different TypeScript version
  7. Node_modules corruption or incomplete installation

How to fix "ts-node: TypeScript version mismatch"

1Check your TypeScript versions

First, identify the conflicting versions:

bash
# Check global TypeScript version
tsc --version

# Check local TypeScript version (from node_modules)
npx tsc --version

# Check ts-node version
npx ts-node --version

Note the versions. The error typically shows something like:

bash
ts-node v10.9.2
ts-node is using TypeScript v5.3.3 but your project uses v5.4.5
2Ensure TypeScript is a local dependency

Make sure TypeScript is installed locally in your project:

bash
# Install TypeScript locally (if not already)
npm install --save-dev typescript

# Or with yarn
yarn add --dev typescript

Verify it's in your package.json:

json
{
  "devDependencies": {
    "typescript": "^5.4.5"
  }
}

Important: Avoid global TypeScript installations when using ts-node locally:

bash
# Uninstall global TypeScript if causing conflicts
npm uninstall -g typescript
3Reinstall dependencies to fix version conflicts

Clear node_modules and reinstall to resolve version conflicts:

bash
# Remove node_modules and lock files
rm -rf node_modules package-lock.json yarn.lock

# Reinstall dependencies
npm install

# Or with yarn
yarn install

For monorepos or complex setups:

bash
# Clear all node_modules in workspace
find . -name "node_modules" -type d -prune -exec rm -rf {} ;

# Reinstall
npm install
4Configure ts-node to use project TypeScript

Create or update ts-node configuration:

Option A: tsconfig.json with ts-node settings

json
{
  "ts-node": {
    "transpileOnly": true,
    "compilerOptions": {
      "module": "commonjs"
    }
  },
  "compilerOptions": {
    // Your TypeScript compiler options
  }
}

Option B: Use ts-node with --compiler option

bash
npx ts-node --compiler typescript index.ts

Option C: Environment variable

bash
TS_NODE_COMPILER=typescript npx ts-node index.ts

Option D: Use ts-node/register in code

javascript
require('ts-node/register');
// Now require your TypeScript files
5Use ts-node with explicit TypeScript path

If you have multiple TypeScript installations, specify the exact path:

bash
# Using npx with explicit path
npx ts-node --compiler ./node_modules/typescript/lib/tsc.js index.ts

# Or in package.json script
{
  "scripts": {
    "start": "ts-node --compiler ./node_modules/typescript/lib/tsc.js index.ts"
  }
}

For programmatic usage:

javascript
const tsNode = require('ts-node');
tsNode.register({
  compiler: require.resolve('typescript')
});
6Verify the fix

Test that ts-node now works correctly:

bash
# Create a simple test file
echo 'console.log("TypeScript version:", require("typescript").version)' > test.ts

# Run with ts-node
npx ts-node test.ts

# Should output your local TypeScript version

If successful, run your actual application:

bash
npx ts-node index.ts
# or
npm start

Advanced notes

### Understanding ts-node's TypeScript Resolution

ts-node resolves TypeScript in this order:
1. --compiler flag or TS_NODE_COMPILER environment variable
2. compiler option in tsconfig.json's ts-node section
3. TypeScript from ts-node's own node_modules
4. TypeScript from your project's node_modules

### Monorepo Considerations

In monorepos (Yarn workspaces, npm workspaces, Lerna):

- Each package should have its own TypeScript dependency
- Use nohoist in Yarn to prevent hoisting conflicts:

json
{
    "workspaces": {
      "packages": ["packages/*"],
      "nohoist": ["**/typescript", "**/ts-node"]
    }
  }

- Consider using tsc --build instead of ts-node for complex monorepos

### Docker and CI/CD Environments

In containerized environments:
- Ensure TypeScript and ts-node are in the same layer
- Clear npm cache during build:

dockerfile
RUN npm ci --cache /tmp/empty-cache

- Use specific version pins to avoid drift

### Alternative: Use tsx or esbuild-runner

If ts-node version conflicts persist, consider alternatives:

bash
# tsx - faster TypeScript execution
npm install --save-dev tsx
npx tsx index.ts

# esbuild-runner - very fast
npm install --save-dev esbuild-runner
npx esr index.ts

### Debugging Version Conflicts

Enable ts-node debugging:

bash
TS_NODE_DEBUG=true npx ts-node index.ts

This shows detailed resolution information including which TypeScript version is being used.

Frequently asked questions

What does "ts-node: TypeScript version mismatch" mean?
ts-node is a TypeScript execution engine that compiles and runs TypeScript code directly without pre-compilation. It requires access to the TypeScript compiler (tsc) to transform TypeScript into JavaScript at runtime. json or node_modules.
How do I fix "ts-node: TypeScript version mismatch"?
This error occurs when the TypeScript version used by ts-node doesn't match the version in your project's dependencies. The mismatch prevents ts-node from properly compiling and executing TypeScript code, requiring version alignment or configuration adjustments.
What causes "ts-node: TypeScript version mismatch"?
Global TypeScript installation conflicts with local project version Multiple TypeScript versions in node_modules (e.g., from different packages) ts-node installed globally but TypeScript installed locally (or vice versa)
Is the "ts-node: TypeScript version mismatch" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading