You're debugging, you Ctrl‑click into a Spring or Jackson method, and you see a decompiled stub with no comments and mangled variable names. Not helpful. The fix is to download the sources JAR for that dependency — Maven can do this automatically, and both Eclipse and IntelliJ will pick them up. Here's exactly how.

Why This Matters – A Personal Story

Early in my career, I spent an entire afternoon trying to figure out why a Spring Data JPA query wasn't working as expected. I stepped through the decompiled code, but all I saw was synthetic variable names like var1, var2, and no comments. It was like reading obfuscated JavaScript.

A senior developer walked by, saw my screen, and said: "Have you downloaded the sources?" I had no idea what he meant. He ran mvn dependency:sources, and suddenly all the Spring classes had proper variable names, meaningful method signatures, and even Javadoc comments. What took me 4 hours to debug was solved in 10 minutes with actual source code. That day, I learned that reading the source is infinitely easier than guessing from bytecode.

Understanding Source JARs

When a Java library is published to Maven Central, it typically ships three artifacts:

• library-1.0.jar — the compiled bytecode (what your app runs)
• library-1.0-sources.jar — the original Java source files
• library-1.0-javadoc.jar — the generated Javadoc HTML

By default, Maven only downloads the first one. The other two are optional, but they transform your debugging experience from reading decompiled bytecode to reading the actual authored source code — with comments, sensible variable names, and all.

Download Sources Only (Local Repository)

This command downloads sources JARs for all your project's dependencies into your local Maven repository (~/.m2/repository), without attaching them to any IDE:

mvn dependency:sources

Add -Dsilent=true to suppress the verbose output:

mvn dependency:sources -Dsilent=true

After this runs, you'll see *-sources.jar files appearing next to the regular JARs in your ~/.m2 folder. Most IDEs (especially IntelliJ IDEA) will detect and attach them automatically.

Download Sources + Attach to Eclipse

For Eclipse specifically, use the eclipse:eclipse goal with the -DdownloadSources=true flag. This regenerates your Eclipse project files (.classpath, .project) and sets Eclipse to use the sources JARs:

mvn eclipse:eclipse -DdownloadSources=true

After running this, refresh your Eclipse project (right‑click → Refresh, or F5). Now when you Ctrl‑click a library class, Eclipse opens the actual source file instead of the decompiled version.

To also download Javadoc attachments (for hover tooltips in Eclipse):

mvn eclipse:eclipse -DdownloadSources=true -DdownloadJavadocs=true

Download Sources + Attach to IntelliJ IDEA

IntelliJ doesn't use Eclipse‑style project files. The easiest approach:

1. Run mvn dependency:sources to download the sources JARs to your local repo.
2. In IntelliJ, press Ctrl+Shift+A (or Cmd+Shift+A), search for Download Sources, and run it — IntelliJ will attach them to all dependencies.

Alternatively, right‑click any dependency in the Maven panel → Download Sources and Documentation.

You can also configure IntelliJ to always download sources automatically: Settings → Build, Execution, Deployment → Build Tools → Maven → Importing → check Automatically download: Sources.

Download Sources for a Specific Dependency

To download sources only for one artifact rather than all dependencies:

# Download sources for a single artifact
mvn dependency:sources -DincludeArtifactIds=spring-core

# Download sources for multiple specific artifacts
mvn dependency:sources -DincludeArtifactIds=spring-core,jackson-databind

This is useful when you're only debugging a specific library and want to save bandwidth and time.

Generating a Sources JAR for Your Own Project

If you're publishing your own library to a Maven repository (Nexus, Artifactory, Maven Central), you should include a sources JAR so your users get the same debugging experience. Use the maven-source-plugin:

# One‑time generation and install to local repo
mvn source:jar install

To always generate the sources JAR during the build, configure the plugin in your pom.xml:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-source-plugin</artifactId>
  <version>3.3.0</version>
  <executions>
    <execution>
      <id>attach-sources</id>
      <goals>
        <goal>jar-no-fork</goal>
      </goals>
    </execution>
  </executions>
</plugin>

After adding this, mvn package or mvn install will produce both mylib-1.0.jar and mylib-1.0-sources.jar.

Generating Javadoc JAR

Similarly, publish a Javadoc JAR alongside your library using the maven-javadoc-plugin:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>3.6.0</version>
  <executions>
    <execution>
      <id>attach-javadocs</id>
      <goals>
        <goal>jar</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Combined with sources, your users get a first‑class experience – source code for debugging and Javadoc for hover tooltips.

What If Sources Aren't Available?

Not every library publishes sources. If a dependency doesn't have a -sources.jar on Maven Central, mvn dependency:sources will simply log a warning and continue without failing the build. In that case:

• IntelliJ will show decompiled code (readable, but not the original).
• Eclipse with the Bytecode Outline plugin can show you the disassembled bytecode.
• Check the library's GitHub repository — you can clone it and attach the source folder manually in your IDE settings.

Common Pitfalls and How to Avoid Them

• Running the wrong command: mvn dependency:source (without the 's') is a common typo – it's dependency:sources (plural). I've made this mistake and wondered why nothing happened.
• Forgetting to refresh the IDE: After downloading sources, the IDE might not pick them up immediately. In IntelliJ, click "Reload Maven Project". In Eclipse, refresh the project.
• Assuming sources are attached forever: If you change your dependencies (add/remove/update), you may need to re‑download sources. I usually run mvn dependency:sources after every major dependency update.
• Not checking the source version: The sources JAR should match the library version. If you're using an older version, the sources might be out of sync. Always use the same version for source and bytecode.
• Forgetting to add -Dsilent=true: Without it, the logs are extremely verbose and can distract you from actual output. I always use -Dsilent=true unless I need to debug the download process itself.

How I Use This Every Day

I've made this part of my daily development routine. When I start a new project, I immediately run mvn dependency:sources -Dsilent=true to get all the sources. In IntelliJ, I've enabled automatic source download so I never forget.

When I'm debugging a framework issue, the first thing I do is Ctrl‑click into the class and check if the source is available. If not, I run mvn dependency:sources -DincludeArtifactIds=spring-core and reload the project. It's become second nature.

I also maintain this habit when publishing libraries – every artifact I publish includes a sources JAR. It's a small courtesy that makes a huge difference to the developer experience.

Summary

To attach sources to your IDE, run mvn dependency:sources (downloads all dependency sources) or mvn eclipse:eclipse -DdownloadSources=true (for Eclipse with project file regeneration). IntelliJ picks up sources JARs from your local Maven repository automatically, or you can trigger a download from the Maven panel. For your own libraries, configure maven-source-plugin to generate a -sources.jar during the build — it's an essential courtesy for anyone who will depend on your library.

Key takeaways:

• Run mvn dependency:sources to download sources for all dependencies.
• For Eclipse, use mvn eclipse:eclipse -DdownloadSources=true.
• For IntelliJ, enable automatic source download in settings, or right‑click dependencies to download sources.
• For your own libraries, add the maven-source-plugin to your pom.xml.
• If sources aren't available, check the library's GitHub and manually attach the source folder.
• Use -Dsilent=true to keep the output clean.

This small investment of time pays dividends every single day you work with Java libraries. Don't settle for decompiled bytecode – download the sources and make your debugging sessions a joy rather than a chore.

Happy debugging – and may your sources always be available!