# Dicoogle: an open source PACS that indexes DICOM metadata

> Dicoogle is an open source picture archiving and communication system that replaces the traditional centralized database with an indexing and retrieval mechanism built to read everything it can find in a medical image, including private DICOM attribute tags, without needing to be re-engineered when a new tag shows up. The core is a Java platform, the interface is a React web application, and the archive itself is a plugin.

**dicoogle/dicoogle** — Dicoogle - Open Source PACS

- Repository: https://github.com/dicoogle/dicoogle
- Website: http://www.dicoogle.com/
- Stars: 535 · Forks: 148
- Language: Java
- License: GPL-3.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/dicoogle-dicoogle

## An archive built around the metadata rather than the files

Dicoogle is an extensible, platform-independent and open-source PACS archive software that replaces the traditional centralized database with a more agile indexing and retrieval mechanism.

The design goal is stated in the next sentence, and it is the whole idea. It was designed to support automatic extraction, indexing and storage of all meta-data detected in medical images, including private DICOM attribute tags, without re-engineering or reconfiguration requirements.

That last clause is the differentiator. A conventional PACS has a schema, and when a manufacturer uses a private tag the archive either ignores it, stores it in a generic slot, or needs a schema change and a migration. Dicoogle's position is that the archive should take the metadata as it finds it, so a research dataset with unusual tags is still fully searchable.

The stack is a Java core with a JavaScript and React web interface, and the topics list the expected vocabulary: dicom, dicom-standard, medical-image-computing, medical-imaging, medical-informatics, metadata, pacs and nodejs. The licence is GPL-3.0, the project home is dicoogle.com, and the default branch is dev.

The branch matters, because the README says this is the development branch for Dicoogle 3, and points at a release/2.X branch for the Dicoogle 2 development line, which is being phased out. So the project is on a major version transition and the two lines are not equivalent.

The releases are 3.5.0 in August 2025, 3.5.1 in December 2025 and 3.6.0 on 2026-05-18, with the last push to the repository on 2026-09-17. There are also two CI badges, one for the Java build with Maven and one for the web application with Node.js, which is a small signal that both halves are built continuously.

## Three papers describe the architecture

Dicoogle is unusual among infrastructure projects in that its architecture is described in the peer reviewed literature, and the README lists three papers.

The most recent is Lebre, Pinho, Jesus, Silva and Costa, Dicoogle Open Source: The Establishment of a New Paradigm in Medical Imaging, published in 2022 in the Journal of Medical Systems, volume 46, article 77, with the DOI 10.1007/s10916-022-01867-3.

Before that came Lebre, Pinho, Silva and Costa, Dicoogle Framework for Medical Imaging Teaching and Research, at the 2020 IEEE Symposium on Computers and Communications, which is the paper that connects the project to its teaching use case.

And the earliest is Valente, Silva, Godinho and Costa, Anatomy of an Extensible Open Source PACS, in the Journal of Digital Imaging in 2016, volume 29, page 284, with the DOI 10.1007/s10278-015-9834-0. That title says what the project is about: the extensibility is the subject, and the anatomy of it is what was written down.

Three papers across six years is the record of a project that has been designed rather than grown, and for an adopter it is a useful thing: the design decisions are documented in a form somebody else has reviewed, rather than only in a wiki page.

The documentation the project points at is a learning pack at bioinformatics-ua.github.io/dicoogle-learning-pack, which includes its own page on building Dicoogle. The official website also carries a few essential plugins for download and a built jar of the platform.

## The jar, the plugins folder and the two ways to run it

The brief documentation in the README gives the setup in four steps, and it is worth following exactly because the folder names are part of the contract.

Copy dicoogle.jar to the installation folder, for example DicoogleDir. Create the folder DicoogleDir/Plugins, which holds the plugins used by your instance of the platform. Copy the desired plugins into it. Run Dicoogle.

The typical setup involves deploying an Indexing and Query Plugin, and the project supplies an implementation of one based on Apache Lucene.

There are two ways to run it, and the difference matters for how you use it. As a server:

```bash
java -jar dicoogle.jar -s
```

And to load the server and open the Dicoogle user interface with the default browser, with the same command and no server flag. The first is the deployment mode, where the interface is reached from another machine, and the second is the local case where the browser opens on the same machine.

Two details are worth noting. The plugin folder name is fixed, DicoogleDir/Plugins, so the install location is not configurable in an obvious way, and the plugin jar is what makes the platform do anything, since the core on its own has no indexer and no store.

Plugin configurations are accessible as files, at DicoogleDir/Plugins/settings/_PluginName_.xml, where the plugin name stands in the middle of the path. Upon initialization, if no configuration file is present, a new one is created with the default values, which means the first start produces the configuration files for you to edit.

## Lucene for the index, a storage plugin for the files

Two plugins do the work, and the README describes them separately because they solve different problems.

The Lucene Index/Query Plugin, shipped as lucene.jar, is based on Apache Lucene to support indexing and querying of DICOM meta-data. With it set, it is possible to index nearly all metadata and perform free text, keyword-based and range-based queries.

The File Storage Plugin, shipped as filestorage.jar, is used for the storage of DICOM files, and this plugin is necessary in order to use Dicoogle as a complete DICOM Storage Provider. The core platform provides a fallback implementation which supports reading, but not storing, files from the local file system.

That sentence defines the boundary precisely. Out of the box the platform can read files that are already on disk, and everything else needs a storage plugin.

How the file plugin works is worth understanding. For storage purposes it maps the DICOM hierarchical organization of Patient, Study, Series and Image into a directory tree in the file system, and every object in the platform may be traced back to its storage location by a URI, similar to file:/tmp/file.

In order to support multiple providers, every storage plugin must define a unique scheme, which maps to the protocol used to store and retrieve content. Its two settings are root-dir, the root directory where the DICOM files will be stored, and scheme, which specifies the scheme and protocol of the file plugin. The README notes that the scheme value is arbitrary but must be unique among all installed plugins, and advises avoiding well known protocol names such as http or file.

That last warning is the whole multi-provider design in one sentence. The scheme is how the platform addresses an object, so it has to be unambiguous across every plugin you have installed.

## Services, the indexer, the watcher and the search page

The web application has three parts that matter in practice.

The management page, under Services and Plugins settings, allows starting and stopping currently running services in real time, and some configurations such as the DICOM service ports may be set there. That is a useful property for a system that has to be stopped and started without a restart.

Indexing a directory is done from the Indexer page on the side bar, where you select a root directory to index. The path is a URI defined according to the storage provider and defaults to the file scheme. In the management page you may also enable the Dicoogle Directory Watcher, which creates a daemon that listens for new files in the root directory, and after selecting the configuration the Apply Settings button must be pressed. When the right settings are saved, the Start button fires the indexing process, and the README warns that this process may take considerable time to complete.

That warning is the practical one. Indexing a large archive is not instant, and the watcher exists so that the incremental case does not need the full job repeated.

The search page enables queries over the indexed metadata. The query syntax is similar to Lucene's Tag:Value query format, but free text searches are also supported, and for inexperienced users an advanced input module may also be used.

There is a subtlety in the provider selection, and the README warns about it. In the search interface it is possible to select which providers to query. Query providers are actually query plugins, installed either in the local instance or in remote instances if the platform is using the WAN plugin. So you must select exactly which providers you want to query in order to retrieve more accurate and faster results.

After running a query, the result browser shows a hierarchical view of the results, with an Export button used to export the query results into a CSV file, and the user selects which tags to include.

## Building the platform and the web application

The repository layout shows the two halves of the project and the tooling around them.

The dicoogle/ directory is the Java core, webcore/ is the React web application, and sdk/ holds the client SDK. There is a dicoogle_web_api.yaml at the root, which is the OpenAPI description of the web API, and that file is the contract a client would be written against. The build is a Maven project with a pom.xml at the root, and .gitmodules for the submodules.

The Dockerfile is the shortest way to see the build requirements, and it is worth reading because it is blunt:

```dockerfile
FROM openjdk:8

WORKDIR /root

RUN apt-get update && \
    apt-get install -y software-properties-common build-essential git maven

RUN git clone https://github.com/bioinformatics-ua/dicoogle
RUN ( cd dicoogle && mvn install && ln -s /root/dicoogle/dicoogle/target/dicoogle.jar /root/ )

CMD ["java","-jar","dicoogle.jar","-s"]
```

So the image is built on OpenJDK 8, installs Maven and the build tools, clones the repository, runs mvn install, symlinks the resulting jar into the root of the container and runs it in server mode. The image builds from source at image build time rather than copying a prebuilt jar, which means the Docker path always runs the current source.

The formatter-config.xml at the root is for the code formatter the project uses, and the CHANGELOG.md tracks the release history.

For learning rather than deployment, the learning pack is the intended route, and it has its own building page, so somebody evaluating Dicoogle does not have to read the Maven build to get a picture of it.

## Where Dicoogle is the wrong choice

There are cases where an open source research PACS is not what you want, and the reasons are structural rather than about the quality of the implementation.

The first is clinical reading. What is described here is an archive with an indexing and retrieval mechanism, a search interface and a result browser. There is no diagnostic viewer in the feature set, no measurement tools and no reporting workflow, so a department that needs to read studies needs different software.

The second is the plugin dependency. Dicoogle becomes useful only when the Lucene indexer and a storage provider are installed and configured, and the storage provider is where the operational decisions live. If your archive lives on object storage, on a PACS archive that speaks its own protocol, or on tape, you need a plugin that does not exist yet, or you write one.

The third is the version transition. The default branch is the Dicoogle 3 development branch and the Dicoogle 2 line is being phased out, so a deployment decision includes picking a line and accepting that one of them is being retired. For a long-lived archive, that is a consideration.

The fourth is the schema freedom trade-off. The automatic extraction of every metadata tag, including private ones, is the feature that makes the archive useful for research datasets with unusual tags. It also means there is no fixed schema to validate against, so a query over an unexpected tag name returns nothing rather than an error.

The alternative approach is a commercial PACS, which gives a vendor support contract, a validated schema, a viewer and a compliance story. The difference in approach is that Dicoogle is an open index over an archive, aimed at research and teaching, where you own the metadata and can query it with full text, while a commercial system is a closed product where the archive is a database with a schema and the search is a subset of what it was designed to answer.

## Conclusion

Dicoogle suits a research imaging group that wants to hold a large DICOM archive, index every tag in it including the private ones, and query it with full text as well as by field, without a vendor database in the middle. It does not suit a clinical department that needs a diagnostic reading workstation, because what is described here is an archive with a search interface rather than a viewer, and it does not suit somebody who wants to run it without thinking about plugins, since the Lucene indexer and the storage provider are separate artefacts you install and configure. Check three things before you deploy it: which line you are on, since the dev branch is Dicoogle 3 and the Dicoogle 2 line is being phased out, which storage provider you will use, because the core can read files from the local file system but cannot store them, and whether your archive needs a scheme that does not collide with a well known protocol, since each storage plugin has to define a unique one. The last push to the repository was on 2026-09-17 and the newest release is 3.6.0.

## FAQ

### What is Dicoogle?

It is an extensible, platform-independent and open-source PACS archive software that replaces the traditional centralized database with a more agile indexing and retrieval mechanism. It is designed to automatically extract, index and store all metadata detected in medical images, including private DICOM attribute tags, without re-engineering or reconfiguration.

### How do I run Dicoogle?

Copy dicoogle.jar to the installation folder, create a DicoogleDir/Plugins folder, put the desired plugins in it and run the platform. With the server flag it runs as a server, and without it the server loads and opens the user interface in the default browser.

### Which plugins does Dicoogle need?

The typical setup needs an Indexing and Query Plugin, and the project supplies a Lucene based one, lucene.jar, which supports free text, keyword-based and range-based queries over DICOM metadata. A storage plugin is also required to use Dicoogle as a complete DICOM Storage Provider, since the core can only read files from the local file system.

### How are storage plugins configured in Dicoogle?

Each plugin has a configuration file at DicoogleDir/Plugins/settings/_PluginName_.xml, created with default values on first start. The file storage plugin has a root-dir setting for where DICOM files are stored and a scheme setting, which must be unique among all installed plugins and should avoid well known protocol names such as http or file.

### Which versions of Dicoogle are supported?

The default branch is the development branch for Dicoogle 3, and the Dicoogle 2 development line lives on the release/2.X branch and is being phased out. The recent releases are 3.5.0, 3.5.1 and 3.6.0, the last published on 2026-05-18.

## Sources

- [dicoogle/dicoogle on GitHub](https://github.com/dicoogle/dicoogle)
- [License: GPL-3.0](https://github.com/dicoogle/dicoogle/blob/dev/LICENSE)
- [Project website](http://www.dicoogle.com/)
- [README](https://github.com/dicoogle/dicoogle/blob/dev/README.md)
- [Releases](https://github.com/dicoogle/dicoogle/releases)

---

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