Download & install¶
Download QuPath for your platform (Windows, Linux, macOS) from GitHub and install ‘as normal’:
- On Windows, if you downloaded an
.msifile then double-click on it to launch the installer
- On Windows, if you downloaded a
.zipthen extract its contents and run the
- On macOS, if you download a
.pkgfile then double-click on it to launch the installer
- On macOS, double-click on the
.dmgfile and drag
QuPath.appto wherever you want to keep it
- On Linux, download and extract the
Recent security changes in Windows and macOS are likely to complicate installation slightly.
See Troubleshooting for more information.
What is QuPath (console).exe?
On Windows, you will see two executable files: QuPath.exe and QuPath (console).exe – perhaps with version numbers incorporated.
You can use either. The only difference between these is that the console version also shows a console that prints text as QuPath runs. This is useful when using the Command line.
When running QuPath for the first time, you will be prompted to specify some setup options.
The default is that QuPath will request 50% of the total memory available. This is generally a reasonable choice, but be aware that the amount of memory available to QuPath is one of the main factors influencing how well the software will perform – and how complex the analysis can be.
Sometimes, your computer may block QuPath from overwriting the configuration file needed to set the maximum memory. If this happens, you wil need to edit this file manually.
See Why can I not set the maximum memory? for instructions.
You can also specify the Region, where it is recommended to leave the default of English (United States) for consistency.
This will help ensure behavior should match with what is shown in this documentation, and seen by other users on the forum.
You can revisit the setup options later under
If you encounter trouble,can be more effective than reinstalling.
If you have trouble installing at all, please see below…
If QuPath does not start, make sure that you are not trying to run it directly from within the
.zip file that you downloaded.
It is important to first extract the files into their own ‘QuPath’ folder, and then run
QuPath.exe from within that.
The QuPath installer gives a scary warning¶
It is expected that Windows will give a scary-looking warning whenever the QuPath installer is first run, as it tries to protect you from software it does not know.
If you would like to get past this screen, press ‘More info’ and the option to ‘Run anyway’ appears.
The QuPath installer does not start¶
If the QuPath installer does not start at all, you may not have administrator privileges on your computer - and therefore cannot install it. Try downloading the
.zip file instead, which should not need such privileges.
Running QuPath on 32-bit Windows is not supported.
Mac users may see one of two similar security message to that experienced by Windows users running the QuPath pkg installer or dmg image.
QuPath cannot be opened¶
If you see the message that QuPath cannot be opened because the developer cannot be verified, you can try right-clicking on the QuPath icon and select Open from the popup menu that appears.
You should then see an option to open QuPath that should work.
QuPath is damaged and can’t be opened¶
Recent macOS changes (first reported in February 2020) may give a different message that QuPath.app is damaged.
This appears to occur because macOS Catalina flags downloads from ‘unidentified developers’ as quarantined, and will not permit them to be opened.
One way to work around this is to remove the flag by opening /Applications/Utilities/Terminal.app and typing
xattr -d com.apple.quarantine /Users/yourname/path/to/QuPath.app
Since macOS (presumably) has your best interests at heart, circumventing its security settings routinely is probably not advisable.
However, the time and resources needed to distribute QuPath as a signed/notarized app to avoid these warnings are currently lacking.
These alternative methods to start QuPath should only be necessary the first time you run it - double-clicking as normal should work afterwards.
The quarantined flag does not always appear to be set, depending upon how the application is downloaded.
For example, these problems may not arise if it is obtained using
QuPath for Linux was compiled on Ubuntu, with best efforts made to include all dependencies, although in the case of OpenSlide this wasn’t entirely successful. You may need to install OpenSlide separately through your package manager.
Known issues are: