[ Kotlin Scripting ] Proposal: Relax the `*.main.kts` Filename Requirement for Kotlin Script Execution

[sdfgsdfgd]

I find myself replacing bash and automation scripts with kotlin scripts everywhere and thats how much I like kotlin.

But the file naming convention is such a hacky, careless, low quality, lazy implementation that requires entire WORDS within kotlin script file names as a prerequisite that its a terrifying experience, just to get tooling support or executability, resolving etc.... Why ?? And can we propose an ultimate solution ? Let's dive in & discover the architectural paths forward.

History

• Kotlin’s scripting support has evolved over time. Initially, .kts scripts could be executed via the compiler’s -script mode, but this support was limited (requiring a special script template and no direct dependency handling). In Kotlin 1.3 (2018), JetBrains introduced a new scripting artifact called kotlin-main-kts​

• By Kotlin 1.3.70 (2020), support for kotlin-main-kts was integrated by default into the Kotlin compiler and IntelliJ IDEA. This meant that the Kotlin compiler and IDE would automatically recognize and handle *.main.kts files without any extra setup​

The Problem

So every language have their own ways to indicate entry points, in python it can detect via AST parsing an if __main__ block, or in most languages default fallback detection relies on main function name defined within the file. In others build configuration overrides the path for source code, but scripts usually, even 50 years ago in UNIX were always flexible, they can even be run without an extension right now.

Can you imagine a scripting language requiring entire words within filenames to be shoved to be recognized as a script, to provide tooling capabilities in our IDEs ? I thought I wouldn't see the day but here we are.

Kotlin’s requirement of a specific file suffix for runnable scripts is unusual when compared to common scripting languages. Most languages rely on either a shebang, explicit interpreter invocation, or special functions to mark entry points, rather than the file’s name. There are examples of file extensions signaling a certain mode (e.g. Node’s module types, or Gradle using .gradle.kts to distinguish Kotlin DSL scripts), but having to include the word “main” in the file name for a standalone script is a Kotlin-specific quirk

Other ecosystems generally treat file naming as a matter of developer preference or tooling convenience, not a prerequisite for execution. This suggests Kotlin could potentially follow suit by using internal markers or context instead of the filename, to decide how to run a script.

Impacts on Usability and Developer Experience.

There are countless effects on dev experience here

1. Discoverability: New users are going to spend days trying to work out why their ridiculous scripts are not even recognized by the IDE. I lost a day on it.
2. Surprise in Tools/Automation: Many tools and environments generate or use scripts in a way that didn’t account for Kotlin’s naming rule. A notable example is GitHub Actions. If one tries to use Kotlin as a scripting shell in Actions, the Action runner creates a temporary file for the script without an extension (as it does for other shells). Kotlin’s CLI then refuses to run that file as a script because it doesn’t end in .main.kts​ lol

In GitHub Actions Issue #813, a developer reported that Kotlin couldn’t be used in a custom action script because “kotlin expects a file name ending in .main.kts, but the runner creates a file without extension”​. This meant Kotlin was essentially incompatible with that workflow until a workaround or change was made. It’s an example of how an unconventional requirement can break integration with external systems that assume a more typical interpreter behavior.

Solution

1. new extension: .ktx
2. or just make all kts executable ?
3. content detection ?

anything is a better idea than enforcing words in file names, almost half a century ago shell scripts were defined to be able to even run without an extension. They still do. We should be able to do much better.

Context & Relevant:

• https://youtrack.jetbrains.com/issue/KT-44242/Allow-running-main.kts-script-that-does-not-end-in-a-main.kts-filename-with-information-from-inside-the-script
• Scripting #77
• https://slack-chats.kotlinlang.org/t/16765016/at-what-point-and-why-did-kts-files-start-needing-to-be-name
• https://github.com/JetBrains/kotlin/blob/dc26f31f3cdfdcee5f77019eb371ff6b2835394a/libraries/tools/kotlin-main-kts/src/org/jetbrains/kotlin/mainKts/scriptDef.kt

[CLOVIS-AI]

We already have .kt and .kts, is adding .ktx really the solution? What makes it better than .main.kts?

.main.kts may be a bit verbose, but it is also relatively clear. Kotlin scripts can be executed by different hosts, and .main.kts is similar to .gradle.kts that Gradle already uses.

[sdfgsdfgd]

The core of the issue isn’t just verbosity—it’s an archaic, rigid, anti-automation design flaw that forces developers to bend to an arbitrary naming convention.

The thread lays out a crystal-clear case for why it’s dumb: no major scripting language does this, and it actively sabotages usability in automation and tooling (GitHub Actions being a prime example).

“.main.kts may be a bit verbose, but it is also relatively clear.”

So is painting road signs on people’s foreheads, but that doesn’t mean it’s a smart way to do navigation.

The argument for ktx is just one possible solution among many, which I agree isn't a good solution, but we should reach for a smart solution within interpreter layer perhaps —detecting entry points based on content would be vastly superior.

is it a straight “Why not just keep the thing we have?” as if stagnation is a compelling counterargument

[JakeWharton]

This repository and its issues are not the place for feature requests. There is already an open YouTrack ticket, which you've found, and should participate in the discussion there.

[CLOVIS-AI]

is it a straight “Why not just keep the thing we have?” as if stagnation is a compelling counterargument

This repository is for language changes. Your proposal is to add .ktx as an alias for .main.kts. You explain it as a major change that is going to make everything easier, but in the end it is just one more name that users have to know and tools have to support. Sure, it is a shorter name, but that's not an improvement marginal enough to add one more thing to learn and one more thing to support in IDEs, code highlighting, etc.

Consider that at this point, GitHub still doesn't color some Kotlin keywords correctly, even though they've been added for multiple years. Let's assume that it takes GitHub 2 years to add support to .ktx. During these two years, you agree that the situation would be objectively worse than the current, right? And that's the case for every tool that exists.