Skip to main content

Thank you for visiting You are using a browser version with limited support for CSS. To obtain the best experience, we recommend you use a more up to date browser (or turn off compatibility mode in Internet Explorer). In the meantime, to ensure continued support, we are displaying the site without styles and JavaScript.

Pycro-Manager: open-source software for customized and reproducible microscope control

To the Editor — Cutting-edge innovations in biological microscopy are increasingly blurring the line between data acquisition and data analysis. Computational microscopy and machine-learning-based methods take this paradigm to an extreme, often producing raw measurements that are not human-interpretable without postprocessing1,2,3. Furthermore, new data-adaptive imaging methods rely on data processing during acquisition to actively control various hardware settings of the microscope.

Testing new ideas and applying them for biological discovery is often impeded by a lack of control software that is capable of meeting demands for speed and performance, integrating new and diverse types of hardware, providing the flexibility to adapt in real time to the data being captured, and providing user-friendly programming interfaces. As a result, researchers often end up developing custom software that works only with specific instruments, using closed-source and/or proprietary programming languages. In addition to slowing development, this lack of a consistent software ecosystem creates barriers to reproduction and replication of new techniques. These include the increased likelihood of bugs in code that is not reused and tested in different contexts, the burden on new users of understanding new code bases, and the extra work of disentangling high-level code that is not properly abstracted from the underlying hardware. In many fields the Python programming language — in particular, the NumPy and SciPy ecosystem4,5 — has emerged as a common framework for reproducing research results that rely on complex, multilayer scientific workflows in a portable, scriptable form6 that is accessible to researchers with various levels of programming experience.

The central challenge of such a consolidated approach in microscopy is the diversity of hardware used in different types of microscopes, ranging from custom-built components on optical tables to turnkey commercial systems. µManager7,8 is an essential tool for controlling microscopes, thanks to an extensive library of ‘device adapters’ for controlling different types of hardware, from cameras to complete microscopes, with a single programming interface. Community contributions of device adapters, plug-ins and scripts provide hundreds of developer-years of microscopy automation.

Despite the power of these libraries, which are written in C++ and Java, they are often difficult to integrate with the latest developments in computer vision and scientific computing, which most readily interface with NumPy. This not only increases the difficulty of developing techniques that rely on both customized data capture and data analysis, but also hinders the dissemination and adoption of these techniques by fragmenting them across multiple tools and programming languages and making them harder to understand and test in new contexts.

Many groups are developing microscopy control software that is written mostly or entirely in Python, including, Python Microscope9, Python Microscopy Environment ( and Tormenta10 (a complete list is at However, these tools are currently limited to specific types of microscopy (for example, super-resolution) and/or support a relatively small number of hardware devices. Thus, despite the potential benefits of such a design, they face an enormous task to match µManager’s flexibility and device support.

To address these needs, we present here Pycro-Manager. Pycro-Manager is built on a translation layer that converts Java objects, functions and data into language-agnostic messages that are reconstituted as Python objects or functions and as NumPy arrays (Fig. 1a and Supplementary Information). As a result, the existing capabilities of µManager can be called as if they had been written in Python, without forcing users to learn Java, forcing Java developers to learn Python, or abandoning of the relative strengths of either language (Supplementary Information).

Fig. 1: Pycro-Manager.

a, Software architecture overview. Grey: the existing parts of µManager provide generic microscope control abstracted from specific hardware, a graphical user interface (GUI), a Java plug-in interface, and an acquisition engine that automates various aspects of data collection. Orange: Pycro-Manager enables access to these components through Python over a network-compatible transport layer, as well as a concise, high-level programming interface for acquiring data. Purple: these provide integration of data acquisition with Python libraries for hardware control, data visualization, scientific computing and so forth. b, Pycro-Manager’s high-level programming interface. The data acquisition process in Pycro-Manager starts with a source of acquisition events (blue), from either programming or a GUI. These events are passed to the acquisition engine (green), which optimizes them to take advantage of hardware triggering where available, sends instructions to hardware and acquires images. The resulting images are then saved and displayed in the GUI (magenta). The three main abstractions of the Pycro-Manager high-level programming interface (acquisition events, acquisition hooks, and image processors) enable fine-grained control and customization of this process. c, Code examples. Code snippets for implementing acquisition events (blue), acquisition hooks (green) and image processors (magenta). (“Python” and the Python logos are trademarks or registered trademarks of the Python Software Foundation, used with permission from the Foundation. C++ logo from

In addition, Pycro-Manager provides a new library of high-level programmatic building blocks (in Python) for customizing data acquisition. These are designed to facilitate creation of complex data acquisitions with concise, readable code while maintaining the flexibility required for customization and the ability to handle multi-terabyte datasets acquired at speeds over 1 GB s–1 (Supplementary Information).

The high-level application programming interface (API) contains three main abstractions: acquisition events, acquisition hooks and image processors (Fig. 1b,c). These building blocks can be used individually or combined for more complex applications. Acquisition events enable customized instructions for how to adjust hardware when acquiring images and how to index those images along arbitrary axes (for example, time, z, etc.) for storage and display. For common microscopy workflows like time-lapses and z-stacks, events can be automatically generated by high-level functions (Fig. 1c). Alternatively, they can be created manually from nested Python lists and dictionaries to allow a greater degree of customization. Acquisition hooks enable the execution of arbitrary Python code concurrently at various stages of the data acquisition process. Image processors give access to the image data as soon as it is acquired, for modification or for use in data-driven feedback loops on the acquisition process.

The combination of Jupyter notebooks ( — interactive documents that consolidate text, code, equations and results — and the Pycro-Manager high-level API provides a means to describe the full workflow of a research project, from data acquisition to analysis to results, thereby facilitating understanding, dissemination and reproduction of new microscopy technologies. For techniques that rely heavily on computation, these notebooks can be as valuable as (or even more valuable than) their corresponding research papers.

In the Supplementary Information and online documentation (, we provide tutorials describing the basic features of Pycro-Manager, as well as Jupyter notebooks outlining sample applications in microscope alignment, light sheet microscopy, integrated sample processing, computational microscopy and machine learning, and the control of microscopes over networks.

The source code and documentation for Pycro-Manager can be found in the Supplementary Information, and future updates will be posted at and

Reporting summary

Further information on experimental design is available in the Nature Research Reporting Summary linked to this paper.


  1. 1.

    Boominathan, V. & Adams, J. K. IEEE Signal Process. Mag. 33, 23–35 (2016).

    Article  Google Scholar 

  2. 2.

    Gustafsson, M. G. L. J. Microsc. 198, 82–87 (2000).

    CAS  Article  Google Scholar 

  3. 3.

    Pavani, S. R. P. & Piestun, R. Opt. Express 16, 22048–22057 (2008).

    CAS  Article  Google Scholar 

  4. 4.

    Harris, C. R. et al. Nature 585, 357–362 (2020).

    CAS  Article  Google Scholar 

  5. 5.

    Virtanen, P. et al. Nat. Methods 17, 261–272 (2020).

    CAS  Article  Google Scholar 

  6. 6.

    Poldrack, R. A., Gorgolewski, K. J. & Varoquaux, G. Annu. Rev. Biomed. Data Sci. 2, 119–138 (2019).

    Article  Google Scholar 

  7. 7.

    Edelstein, A., Amodaj, N., Hoover, K., Vale, R. & Stuurman, N. Curr. Protoc. Mol. Biol. 92, 1–17 (2010).

    Article  Google Scholar 

  8. 8.

    Edelstein, A. D. et al. J. Biol. Methods 1, 10 (2014).

    Article  Google Scholar 

  9. 9.

    Miguel, D. et al. Preprint at bioRxiv (2021).

  10. 10.

    Barabas, F. M., Masullo, L. A. & Stefani, F. D. Rev. Sci. Instrum. 87, 126103 (2016).

    Article  Google Scholar 

Download references


We thank S. van der Walt and K. Marchuk for discussion during development. This project was funded by Packard Fellowship and Chan Zuckerberg Biohub Investigator Awards to L.W.; STROBE: A NSF Science and Technology Center; an NSF Graduate Research Fellowship awarded to H.P.; a Berkeley Institute for Data Science/UCSF Bakar Computational Health Sciences Institute Fellowship awarded to H.P. with support from the Koret Foundation, the Gordon and Betty Moore Foundation, and the Alfred P. Sloan Foundation to the University of California, Berkeley. K.W.E., B.L. and M.T. were funded by the Chan Zuckerberg Initiative and NIH grant P41GM135019.

Author information




Initial concept: H.P. Early development and planning: H.P., N.S., L.W. Development of core libraries: H.P., N.S., I.E.I., N.M.A, M.T., B.C., I.H., S.B.M., L.W. Application development, testing, bug finding, and supervision: H.P., I.E.I., W.O., B.L., B.Y., G.Z., R.M., M.A.,D.P.S., W.J., R.D., S.K., L.A.R., J.R.T., K.W.E., E.L., S.B.M, L.W. Manuscript writing: H.P., N.S., I.E.I., S.M., L.W.

Corresponding author

Correspondence to Henry Pinkard.

Ethics declarations

Competing interests

The authors declare no competing interests.

Additional information

Peer review information Nature Methods thanks Robert Haase and Dominic Waithe for their contribution to the peer review of this work.

Supplementary information

Supplementary Information

Supplementary Discussion: Applications, Performance, Background and Motivation, Architecture and Design, Documentation of Pycro-Manager at publication time

Reporting Summary

Supplementary software

Source code of Pycro-Manager at publication time

Rights and permissions

Reprints and Permissions

About this article

Verify currency and authenticity via CrossMark

Cite this article

Pinkard, H., Stuurman, N., Ivanov, I.E. et al. Pycro-Manager: open-source software for customized and reproducible microscope control. Nat Methods 18, 226–228 (2021).

Download citation


Quick links

Nature Briefing

Sign up for the Nature Briefing newsletter — what matters in science, free to your inbox daily.

Get the most important science stories of the day, free in your inbox. Sign up for Nature Briefing