pypylon is the official Python language binding for the Basler pylon C++ APIs. It enables Python applications to control and acquire images from Basler machine vision products, e.g. cameras. Furthermore, the pylon Data Processing API allows you to perform image processing tasks.

Note: This README was updated for pypylon 26.6. pypylon 26.6 introduces breaking changes. While most existing code is expected to remain functional, check the changelog for a full list of affected areas.

Background information about usage of pypylon, programming samples and Jupyter notebooks can also be found at pypylon-samples (may not always reflect the latest pypylon API/style).

Getting Started

📖 A detailed pypylon Programmer's Guide can be found on GitHub as well as in the Basler Product Documentation.

• Install pylon This is strongly recommended but not mandatory. See known issues for further details.
• Install pypylon: pip3 install pypylon For more installation options and the supported systems please read the Installation paragraph.
• Look at samples/pylon/grab/grab.py or use the following snippet:

from pypylon import pylon

# Create an InstantCamera object with the camera device found first.
# The with statement creates, opens the camera and destroys it automatically.
with pylon.InstantCamera(pylon.FirstFound) as camera:
    print("Using device:", camera.DeviceInfo.ModelName)

    # Demonstrate some feature access using the pylon parameter API.
    camera.Width.TrySetToMaximum()

    # Start the grabbing of 100 images.
    camera.StartGrabbingMax(100)

    while camera.IsGrabbing():
        # The grab result is released automatically at the end of the with block.
        with camera.RetrieveResult(
            5000, pylon.TimeoutHandling_ThrowException
        ) as grab_result:
            if grab_result.GrabSucceeded():
                # Some camera models use a GenICam Generic Data Container (GenDC) format.
                # For single grabbed images, a data component is emulated automatically.
                with grab_result.GetFirstImageDataComponent() as image_data_component:
                        # Access the image data.
                        img = image_data_component.Array
                        print(f"SizeX: {image_data_component.Width};"
                              f"SizeY: {image_data_component.Height}; "
                              f"Gray value of first pixel: {img[0, 0]}")

Getting Started with pylon Data Processing

• pypylon additionally supports the pylon Data Processing API extension.
• The pylon Workbench allows you to create image processing designs using a graphical editor.
• Hint: The pylondataprocessing tests can optionally be used as a source of information about the syntax of the API.
• Look at samples/pylondataprocessing/barcode/barcode.py or use the following snippet:

from pypylon import pylon
from pypylon import pylondataprocessing

# This object collects the output data. Create it before the recipe so it outlives it.
result_collector = pylondataprocessing.GenericOutputObserver()

# Create a recipe object representing a recipe file created with the pylon Viewer Workbench.
with pylondataprocessing.Recipe() as recipe:
    recipe.Load("barcode.precipe")
    recipe.RegisterAllOutputsObserver(result_collector, pylon.RegistrationMode_Append)
    recipe.Start()

    for i in range(100):
        if result_collector.WaitObject.Wait(5000):
            result = result_collector.RetrieveResult()
            # Print the barcodes.
            barcodes = result["Barcodes"]
            if not barcodes.HasError():
                for index in range(barcodes.NumArrayValues):
                    print(barcodes[index].ToString())
            else:
                print("Error:", barcodes.ErrorDescription)
        else:
            print("Result timeout")
            break

Update your code to pypylon >= 26.06

The current pypylon implementation allows direct feature assignment:

cam.Gain = 42

This assignment style is deprecated with pypylon 3.0.0, as it prevents full typing support for pypylon.

The recommended assignment style is now:

cam.Gain.Value = 42

To identify the locations in your code that have to be updated, run with enabled warnings:

PYTHONWARNINGS=default python script.py

pypylon now also ships the full pylon parameter API (classes derived from Pylon::CParameter). It adds many convenience methods on parameters, such as camera.ExposureTime.SetToMaximum(), camera.PixelFormat.TrySetValue("Mono8") and camera.ExposureTime.GetValueOrDefault(default_value). In addition, pylon.InstantCamera supports the context manager protocol, so it can be used in a with statement to be opened and closed automatically. See the samples and the style guidelines in the context folder for the recommended coding style.

Installation

Prerequisites

• Installed pylon For the binary installation this is not mandatory but strongly recommended. See known issues for further details.
• Installed python with pip
• Installed CodeMeter Runtime when you want to use pylon vTools and the pylon Data Processing API extension on your platform.

pylon OS Versions and Features

Please note that the pylon Software Suite may support different operating system versions and features than pypylon. For latest information on pylon refer to: https://www.baslerweb.com/en/software/pylon/ In addition, check the release notes of your pylon installation. For instance:

• pylon Software Suite 26.06 supports Windows 10/11 64 bit, Linux x86_64 and Linux aarch64 with glibc version >= 2.31 or newer, macOS Sonoma or newer.
• pylon vTools are supported on pylon 7.0.0 and newer.
• pylon vTools are supported on pypylon 3.0 and newer only on Windows 10/11 64 bit, Linux x86_64 and Linux aarch64.
• For pylon vTools that require a license refer to: https://www.baslerweb.com/en/software/pylon-vtools/
• CXP-12: To use CXP with pypylon >= 4.0.0 you need to install the CXP GenTL producer and drivers using the pylon Software Suite setup.
• For accessing Basler 3D cameras, e.g. Basler blaze, installation of pylon Software Suite 8.1.0 or newer and the latest pylon Supplementary Package for blaze is required.

Binary Installation

The easiest way to get pypylon is to install a prebuild wheel. Binary releases for most architectures are available on pypi**. To install pypylon open your favourite terminal and run:

pip3 install pypylon

Prebuilt pypylon wheels on PyPI are available for the Python versions and platforms listed below:

Additional Notes on binary packages:

• (*) The linux 64bit binaries are manylinux_2_31 conformant. This is roughly equivalent to a minimum glibc version >= 2.31. ⚠️ You need at least pip 20.3 to install them.
• (**) macOS binaries are built for macOS >= 14.0 (Sonoma)

Installation from Source

Building the pypylon bindings is supported and tested on Windows, Linux and macOS

You need a few more things to compile pypylon:

• An installation of pylon SDK for your platform
• A compiler for your system (Visual Studio on Windows, gcc on linux, xCode commandline tools on macOS)
• Python development files (e.g. sudo apt install python-dev on linux)
• swig 4.3
  • For all 64bit platforms you can install the tool via pip install "swig==4.3"

To build pypylon from source:

git clone https://github.com/basler/pypylon.git
cd pypylon
pip install .

If pylon SDK is not installed in a default location you have to specify the location from the environment

• on Linux: export PYLON_ROOT=<installation directory of pylon SDK>
• on macOS: export PYLON_FRAMEWORK_LOCATION=<framework base folder that contains pylon.framework>

Development

Pull requests to pypylon are very welcome. To help you getting started with pypylon improvements, here are some hints:

If you use an AI coding assistant, see AGENTS.md for the repository map, build/test commands, and coding-style references.

Starting Development

python setup.py develop

This will "link" the local pypylon source directory into your python installation. It will not package the pylon libraries and always use the installed pylon. After changing pypylon, execute python setup.py build and test...

Running Unit Tests

NOTE: The unit tests try to import pypylon...., so they run against the installed version of pypylon.

Run the hardware-free (Camera Emulation) suites the same way CI does:

pip install pytest numpy
pytest tests/genicam tests/pylon/emulated tests/pylondataprocessing

The tests/pylon/usb and tests/pylon/gigE suites require real cameras.

Known Issues

• For USB 3.0 cameras to work on Linux, you need to install appropriate udev rules. The easiest way to get them is to install the official pylon package.

Support

You are welcome to post bug reports and questions about pypylon on GitHub. Please check the pypylon Programmer's Guide first.

For questions about cameras, the pylon SDK (C++/.NET), pylon vTools, or additional technical support for business customers, please reach out to our official support team.