pymmcore-plus

Micro-Manager Device Adapters¶

Just like the underlying pymmcore library, pymmcore-plus relies on the device adapters and C++ core provided by mmCoreAndDevices. (The Python packages themselves are covered on the Installation page.)

Installing Micro-Manager device adapters¶

The device adapters can be installed in two ways:

1. Use the mmcore command line tool

   pymmcore-plus provides a quick way to install the latest compatible version of Micro-Manager:

   mmcore install
   

   This will download the most recent nightly build of Micro-Manager that matches your version of pymmcore and, by default, place it in a pymmcore-plus/mm folder in the user's data directory:

   OS	Path
   Windows	C:\Users\UserName\AppData\Local\pymmcore-plus\pymmcore-plus\mm
   macOS	~/Library/Application Support/pymmcore-plus/mm
   Linux	~/.local/share/pymmcore-plus/mm

   If you would like to modify the location of the installation, or the release of Micro-Manager to install, you can use the --dest and --release flags respectively.

   For more information on the install command, run:

   mmcore install --help
   

   To explore all the mmcore command line tool functionalities, run mmcore --help (or see the CLI reference).

2. Download manually from micro-manager.org

   Go to the Micro-Manager nightly builds page and download a build for your operating system whose device interface version matches your pymmcore (see below). This is not necessarily the latest release.

Showing the current installation¶

To see which Micro-Manager installations pymmcore-plus has found, and which one it is using, run:

mmcore list

The output looks something like this (the active installation is marked with ➤):

Required pymmcore device interface version: 75

📁 ~/Library/Application Support/pymmcore-plus/mm
   ➤ Micro-Manager-75.20260226 (DIV 75) (active)
   • Micro-Manager-74.20260129 (DIV 74) (incompatible)

From Python, you can use find_micromanager:

python -c "from pymmcore_plus import find_micromanager; print(find_micromanager())"

Setting the active installation¶

When you create a CMMCorePlus, pymmcore-plus looks for device adapters in the following places, and uses the first one whose device interface version matches pymmcore:

1. The MICROMANAGER_PATH environment variable (always used, if set).
2. A path previously selected with mmcore use (see below). If it's no longer compatible, it is forgotten (with a warning).
3. The mmcore install folder in the user data directory (see the table above). If there are several compatible installations there, the last one in alphabetical order is used.
4. The mm-test-adapters Python package, if it is installed.
5. A Micro-Manager* folder in the default Micro-Manager install location: C:\Program Files\ on Windows, /Applications/ on macOS, and /usr/local/lib/ on Linux.

So if you already have Micro-Manager installed in the default location, and mmcore list says that it is compatible, it will be found automatically (unless one of the earlier locations also has a compatible installation). If mmcore list says that it's incompatible, run mmcore install to get a compatible set of adapters.

To override the device adapter search path for a single session (or script), set the MICROMANAGER_PATH environment variable:

export MICROMANAGER_PATH=/path/to/installation

(For a single core object, you can also pass the folder directly: CMMCorePlus(mm_path="/path/to/installation").)

If you want to permanently set the Micro-Manager installation path that pymmcore-plus uses, you can use the mmcore use command:

mmcore use <some path or pattern>

... where <some path or pattern> is either a path to an existing directory (containing Micro-Manager device adapters) or a pattern to match against directories returned by find_micromanager.

Alternatively, you can use the use_micromanager function, passing either a path to an existing directory, or a pattern to match against directories returned by find_micromanager:

python -c "from pymmcore_plus import use_micromanager; use_micromanager(path=..., pattern=...)"

Building device adapters¶

On Linux and Apple Silicon there are no pre-built Micro-Manager adapters beyond the test devices, so you will need to build the C++ core and device adapters yourself from mmCoreAndDevices. To do that, follow the build instructions in the micro-manager repo, then point pymmcore-plus at the folder with mmcore use.

On macOS and Linux, mmcore build-dev can also clone the repository and build a few adapters for you (DemoCamera, Utilities and SequenceTester by default, or the names you pass it). Not all adapters will build this way, and you'll need the build tools described in the instructions above. Run mmcore build-dev --help for the options.

Understanding device interface versions¶

Micro-Manager's C++ layer (called MMCore) controls devices via adapters that are compiled into platform-specific shared libraries. These libraries are always compiled to work with a specific "device interface version" expected by the MMCore object itself. If you try to load a device adapter with a device interface version that does not match the version expected by the core, then you will get an error.

pymmcore is a library that wraps the C++ code and makes it available to Python. It has a 5-number version string that looks something like 12.5.1.75.0. The first three parts (here: 12.5.1) represent the version of the MMCore library. The next number (here: 75) is the device interface version that pymmcore expects. (The last number is a pymmcore-specific build number). To query version information of your installed libraries you can run:

mmcore --version

mmcore install -r 20260225

Here is a list of the latest device interface numbers, the date of the first nightly build where they were available, the last nightly build date to support that version, and the commit in mmCoreAndDevices that bumped the version.