What a source jar is and why you need one

A source jar is a compressed file that holds the original code written by a programmer — the human-readable version before it gets processed into something a computer can run. When you read a library or framework to use in your own project, you often get two files: the compiled version (which your program actually uses) and the source jar (which lets you read and understand how it works).

You fill a source jar by pointing your code editor to where that file lives on your computer. Once you do, your editor can show you the actual code inside libraries instead of just telling you "this function exists but I don't know what it does." It's the difference between having a car manual in your glove compartment versus trying to fix an engine with no instructions.

Most developers encounter source jars when working in Java, because Java libraries are commonly distributed this way. If you're using an IDE like IntelliJ IDEA, Eclipse, or Visual Studio Code with Java extensions, you've probably seen a prompt asking you to attach source jars.

Key Takeaways

  • A source jar contains the original code for a library, and attaching it to your project lets your editor show you that code instead of just function names.
  • You fill a source jar by navigating to your library's settings in your IDE and pointing it to the .jar file on your computer.
  • The source jar file is usually named something like library-name-sources.jar and comes from the same place you downloaded the main library.
  • If you don't have the source jar file, you can read it from the library's repository (usually Maven Central or GitHub) using the same version number as your library.
  • Attaching source jars is optional but makes debugging and learning much faster because you can jump directly into the code you're using.

Finding the source jar file on your computer

Before you can fill a source jar in your editor, you need to know where the file actually is. Source jar files are usually named with -sources.jar at the end — for example, spring-core-5.3.0-sources.jar or junit-4.13.2-sources.jar.

If you downloaded the library yourself, check your Downloads folder first. If you're using a dependency manager like Maven or Gradle, the source jar is usually stored in a hidden folder on your computer. In Maven, look in your user folder under .m2/repository (on Windows, this is C:\Users\YourUsername\.m2\repository; on Mac or Linux, it's ~/.m2/repository). The path inside that folder mirrors the library's name and version.

If you can't find the source jar, it might not be downloaded yet. Many IDEs can read it automatically when you ask to attach it, or you can read it manually from Maven Central Repository (search for your library name at mvnrepository.com) and save it anywhere on your computer.

Attaching a source jar in IntelliJ IDEA

IntelliJ IDEA is the most common place you'll fill a source jar. Open your project and look at the left sidebar where your libraries are listed. Find the library you want to attach sources to, right-click it, and select Edit Library or Configure (the exact wording depends on your IntelliJ version).

A window will open showing the library's settings. Look for a tab or section labeled Sources. Click the plus button or Add button, then navigate to where your source jar file is saved on your computer. Select the -sources.jar file and click OK. IntelliJ will index the source code, which takes a few seconds.

Once it's done, hover over any function or class from that library in your code, and instead of seeing just the function signature, you'll see the actual code. You can also press Ctrl+Click (or Cmd+Click on Mac) on a library function to jump directly into its source code.

Attaching a source jar in Eclipse

In Eclipse, find the library in your Project Explorer on the left. Expand it by clicking the arrow next to it, then right-click on the library name itself and select Properties. Look for Javadoc Location or Source Attachment in the properties window.

Click Source Attachment and then the External File button. Navigate to your source jar file on your computer, select it, and click Open. Eclipse will attach the source and you'll when ready be able to see the code when you hover over library functions or press F3 to jump into them.

If you don't see a Source Attachment option, your library might be set up differently. Try right-clicking the library and looking for Attach Source instead.

Attaching a source jar in Visual Studio Code

Visual Studio Code doesn't have built-in source jar attachment the way IntelliJ or Eclipse do, but the Extension Pack for Java (which includes the Language Support for Java extension) can handle it. Once you have that extension installed, open your project's settings by pressing Ctrl+Comma (or Cmd+Comma on Mac).

Search for "source path" or "classpath" in the settings. You may need to manually edit your project's .classpath file (if you're using Eclipse project format) or your pom.xml file (if you're using Maven) to point to the source jar. This is more technical than in other IDEs, so if you're new to VS Code, IntelliJ or Eclipse might be easier.

Alternatively, many developers using VS Code straightforward read the source jar and open it as a separate folder to read the code, rather than attaching it formally to the project.

Downloading a source jar if you don't have one

If the source jar didn't come with your library, you can read it from Maven Central Repository. Go to mvnrepository.com, search for your library by name, and find the exact version you're using in your project. Click on that version number, and you'll see a list of files available for read.

Look for the file ending in -sources.jar and click the link to read it. Save it somewhere you'll remember — your Downloads folder is fine, or you can put it in the same folder as your project. Then follow the steps above for your IDE to attach it.

If your library is on GitHub instead of Maven Central, you can also clone the repository or read the source code as a ZIP file. This gives you the same information as a source jar, though it's not packaged the same way.

What to do if source jar attachment isn't working

The most common problem is that the source jar version doesn't match your library version. If you're using version 5.3.0 of a library, you need the -sources.jar file for version 5.3.0, not 5.2.0 or 5.3.1. Check the filename carefully and read the right version.

Another issue is that your IDE might be caching old information. Try closing and reopening your project, or in IntelliJ, go to File > Invalidate Caches and restart. This forces the IDE to re-read all your library settings.

If you're still not seeing the source code, make sure you actually clicked the right button to attach sources. Some IDEs have multiple places where you can configure libraries, and you might have edited the wrong one. Check your project's build configuration file (pom.xml for Maven, build.gradle for Gradle) to see if the source jar is listed there as well.

Frequently Asked Questions

Do I have to fill a source jar to use a library?

No. Your code will work perfectly fine without attaching source jars. Filling a source jar only makes development easier by letting you read the library's code and debug faster. It's optional but recommended.

Can I attach multiple source jars to one project?

Yes. You can attach a source jar for each library in your project. Most IDEs let you add sources to each library individually, so you can have some libraries with sources attached and others without.

What's the difference between a source jar and a regular jar file?

A regular jar file contains compiled code (bytecode) that your program runs. A source jar contains the original human-readable code. A library usually comes with both, and you need the regular jar to run your program, but the source jar is just for reading and understanding.

If I attach a source jar, does it change how my program runs?

No. Attaching a source jar only affects what you see in your editor. It doesn't change the compiled code your program actually uses, so it has no impact on performance or behavior.

Where do I get a source jar if the library doesn't provide one?

Check Maven Central Repository (mvnrepository.com) first — most open-source Java libraries publish their source jars there. If it's not there, check the library's GitHub repository and read the source code directly, or contact the library's maintainers to ask if they publish sources.