# sbt-eclipse: generating Eclipse project files from sbt

> sbt-eclipse is an Apache 2.0 licensed sbt plugin that turns a build into Eclipse project definitions, so a Scala developer can open the project in the Eclipse IDE without hand writing the metadata. The judgement is that it is a narrow, well documented plugin with a versioning split that matters, since the 6.x line needs sbt 1.4 and the older coordinate is for everything before that.

**sbt/sbt-eclipse** — Plugin for sbt to create Eclipse project definitions

- Repository: https://github.com/sbt/sbt-eclipse
- Stars: 712 · Forks: 163
- Language: Scala
- License: Apache-2.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/sbt-sbt-eclipse

## A plugin whose whole job is writing project files

sbt-eclipse is a plugin for sbt that creates Eclipse project definitions, and the readme is careful to point at the wiki for how to configure it rather than duplicating the documentation in the readme.

The problem it solves is old and simple. sbt is a build tool, and a build tool knows the classpath, the dependencies and the source directories, but Eclipse does not read a build definition, it reads a project folder with a .project file and a .classpath file in it. Without help, adopting Eclipse for an sbt project means writing those by hand, which is exactly the kind of chore that stops people switching.

The plugin makes the build describe itself to the IDE. Running one command in sbt produces the Eclipse project files, and the developer imports them once and then has a working project with the right dependencies and the right source roots.

The project is Apache 2.0 licensed, written in Scala, and it lives in the sbt organisation on GitHub, which tells you it is treated as part of the sbt ecosystem rather than as an independent add-on. The release history shows 6.0.0 on 2022-09-23, 6.1.0 on 2023-12-11 and 6.2.0 on 2023-12-15, and the last push to the repository was on 2026-09-24.

The repository itself is small, with a build.sbt, the source under src, a project directory for the build definition, a notes directory, and the GitHub workflow that runs the build.

## Where the plugin declaration goes

The installation has two halves, and the first half is about where the declaration lives rather than about what it says.

The readme says to open the plugin definition file, or create one if it does not exist, and there are two of them. The global file, for version 1.0 and up, is at ~/.sbt/SBT_VERSION/plugins/plugins.sbt, and the project-specific file is at PROJECT_DIR/project/plugins.sbt.

The path with the version in it is the detail that trips people up. The global plugin directory is versioned by the sbt version, because a global plugin is resolved by the launcher for a particular sbt release, so ~/.sbt/1.4.0/plugins and ~/.sbt/0.13.18/plugins hold different things. The project file has no version in the path, because it belongs to the project and is read by whatever sbt runs it.

So the choice is a choice about scope. A project file means the plugin is declared in version control with the project and every developer gets it automatically, which is the right answer for a team. A global file means one installation per machine, which is the right answer for a person experimenting with the IDE on one build.

The readme also links the contribution policy and the licence information, both of which are short sections of their own in the document.

## The two coordinates, and the sbt version that decides

The declaration itself is a single line, and there are two of them depending on the sbt version you are on.

```sbt
addSbtPlugin("com.github.sbt" % "sbt-eclipse" % "6.0.0")

// For older sbt versions (< 1.4.0)
addSbtPlugin("com.typesafe.sbteclipse" % "sbteclipse-plugin" % "5.2.4")
```

The rule is stated just above them. Version 6.x and later only supports sbt 1.4 and above, and 5.2.4 or older is the line to use for previous versions of sbt.

The interesting part is the organisation, because it changes the coordinate entirely. The current line is published under com.github.sbt, which is the convention for a plugin built with the sbt plugin build, and the older one is under com.typesafe.sbteclipse with the artefact named sbteclipse-plugin, which is the Typesafe organisation and the name it had before the sbt organisation took the project over.

So a build migrating from the old line to the new one is not just a version bump, it is a change of group and artefact id, and a copy of the old declaration left in place will keep resolving to the 5.2.4 line.

The readme points at the wiki for the configuration options, which is where the project keeps the details of what the generated files contain.

## One command in sbt, one import in Eclipse

The usage is one command in the build, and then one step in the IDE.

In sbt you run the command eclipse, which is the plugin's only task, and it creates the Eclipse project files for the current project.

In Eclipse you then use the Import Wizard, and the option to import Existing Projects into Workspace, pointing it at the directory the plugin wrote. After that the project is a normal Eclipse project with the right source folders and the right classpath.

The split is worth noticing because it is the shape of every tool of this kind. The generator and the consumer are separate programs with separate lifecycles, the generator runs in the build and the consumer runs in the IDE, and the files on disk are the interface between them. That also means the workflow is the familiar one: change the build, rerun the command, reload the project in the IDE.

The reason a project like this exists at all, in a world where several editors can read an sbt build directly, is historical as much as practical. A team that has been building with sbt for years has a build it does not want to rewrite, and the cost of getting that build into an IDE is the only thing standing between the team and a different editor. Generating the project files removes that cost without asking anyone to change how the software is built.

## A tag makes a release, and main makes a snapshot

The release process for the plugin is described in the readme, and it is a useful example of a small project with a reproducible publishing rule.

Maintainers must run git tag, or use the GitHub interface, to tag a release. As soon as a tag is pushed to the repository, or created through the interface, a release is pushed to the Maven Central repository, under the com/github/sbt path. And on each push to the main branch, snapshots are published to the Sonatype snapshot repository.

The result is that a plugin version is a tag, and the tag is the single source of truth for what was published. There is no separate release process with its own version file to keep in sync, and the snapshot repository means that a developer can test the main branch of the plugin against their project without waiting for a release.

The path on Maven Central is worth noting for anyone pinning the dependency. It is under com/github/sbt, which is the inverse of the group id, the standard layout for artefacts published with the sbt plugin build rather than with a manual repository configuration.

The readme is also explicit about the contribution policy, that contributions via GitHub pull requests are gladly accepted from their original author, which is a short sentence that says the maintainers want patches from the people who found the problems.

## The Scala Steward keeps the dependencies honest

Two of the badges in the readme tell you how the project is maintained, and neither of them is about the code.

The first is the Scala Steward badge. The Scala Steward is a service that watches the dependencies of a Scala project and opens pull requests when a new version of a library is released, which for a build plugin is most of the maintenance work. A plugin that depends on the sbt API has to move when sbt moves, and a bot that opens the pull request is a much better outcome than a plugin that silently stops working with a new sbt release.

The second is the repository size badge, which is a curiosity rather than a feature, but it does tell you the scale of the thing. The project is a plugin with a build.sbt, a source directory, a project directory for its own build definition, a notes directory and a GitHub workflow, which is a small repository by any measure.

The build status badge points at a workflow named build-test, which is the usual name for the continuous integration that compiles the plugin against several sbt versions. Given that the plugin's compatibility with sbt versions is the thing that breaks, a matrix of sbt versions in that workflow is the part of the maintenance that matters, and the version split in the coordinates is the part users feel.

Taken together, the picture is of a small, conventional, well behaved plugin that does one job, that keeps working by being rebuilt, and that the sbt organisation maintains because the IDE integration is still the thing people ask for.

## Conclusion

sbt-eclipse fits a team that builds with sbt and develops in Eclipse, or a team that wants to try Eclipse on an existing sbt project without rewriting anything, because the plugin writes the project metadata from the build it already has. It is the wrong choice if your IDE already reads sbt builds directly, since several modern editors do, and it is the wrong choice if you are on sbt older than 1.4, because the 6.x coordinate will not work there and the older coordinate is a different artefact with a different organisation in it. Before you add it, check which sbt version your build uses and pick the matching coordinate, and remember that the plugin generates files rather than replacing the IDE, so the import step in Eclipse is still part of the workflow.

## FAQ

### What does the sbt-eclipse plugin do?

It creates Eclipse project definitions from your sbt build, so an Eclipse user can import the project rather than writing the project metadata by hand. The plugin is Apache 2.0 licensed, written in Scala and published to Maven Central under the com/github/sbt path.

### How do I add sbt-eclipse to a build?

Add the plugin to the definition file, either the global one at ~/.sbt/SBT_VERSION/plugins/plugins.sbt or the project one at PROJECT_DIR/project/plugins.sbt, with addSbtPlugin("com.github.sbt" % "sbt-eclipse" % "6.0.0") for sbt 1.4 and above.

### What is the difference between the two plugin coordinates?

The 6.x line, published under com.github.sbt, requires sbt 1.4 or newer. Older sbt versions need 5.2.4 or earlier, which is a different artefact under com.typesafe.sbteclipse with the name sbteclipse-plugin, so migrating between them changes the group and the artefact id.

### How do I use the generated Eclipse project?

Run the eclipse command in sbt to create the project files, then in Eclipse use the Import Wizard and the option to import Existing Projects into Workspace. The readme points at the wiki for the configuration options.

## Sources

- [Issues](https://github.com/sbt/sbt-eclipse/issues)
- [License: Apache-2.0](https://github.com/sbt/sbt-eclipse/blob/main/LICENSE)
- [README](https://github.com/sbt/sbt-eclipse/blob/main/README.md)
- [Releases](https://github.com/sbt/sbt-eclipse/releases)
- [sbt/sbt-eclipse on GitHub](https://github.com/sbt/sbt-eclipse)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sbt-sbt-eclipse