Use a channel-provided virtual package detector

A detector is an installable package that reports system capabilities as virtual packages. In this tutorial you will learn how to configure an already uploaded detector on prefix.dev so that it can be detected by a conda client such as Pixi.

Before you start

You need permission to manage the channel's settings. This example assumes the detector and application packages are already uploaded to that channel.

This tutorial uses two illustrative packages: fpga-detect reports __example_fpga, and fpga-tools uses that capability for FPGA-accelerated data processing. These names do not refer to public packages. Replace them and https://prefix.dev/my-channel with your own packages, virtual package, and channel URL.

An FPGA (Field-Programmable Gate Array) is a chip with reconfigurable digital circuitry that can serve as a hardware accelerator. When Pixi runs it, this hypothetical fpga-detect detector would query the board's driver or runtime to check whether a supported FPGA is suitable. It would write the result as one of the JSON reports below.

When a supported FPGA is available, the detector reports:

{
  "version": 1,
  "virtual_packages": {
    "__example_fpga": { "version": "1" }
  }
}

When it is absent, the detector reports:

{
  "version": 1,
  "virtual_packages": {
    "__example_fpga": null
  }
}

fpga-detect is the package you register. __example_fpga is the capability it reports, not a package the user installs. The top-level version identifies the detector protocol. This example uses capability version "1" to mean that a supported FPGA is usable, not to identify its model or firmware.

The already-uploaded fpga-tools package has this run-dependency fragment in its recipe:

requirements:
  run:
    - __example_fpga >=1

Register the detector

Open your channel on prefix.dev, then go to Settings > Virtual Package Detectors.

Under Add registration, enter:

• Detector package: fpga-detect

• Publication subdir: noarch

• Reported virtual packages: __example_fpga

Click Save changes.

The publication subdir determines where clients discover the registration. Use noarch when clients on all platforms should discover it. This does not require a noarch package: you can publish platform-specific builds of fpga-detect, but each client needs a runnable build and dependencies for its host.

Use a platform subdir instead when discovery should be limited to that platform. For example, choose linux-64 if the detector only supports Linux x86-64.

Wait for publication

Saving the settings schedules metadata publication. Wait for Metadata up to date under Metadata publication before trying the client example.

Install a package with Pixi

Create a pixi.toml with your channel URL. Replace linux-64 with your platform, such as osx-arm64 on macOS with Apple Silicon or win-64 on Windows x86-64. Both packages and their dependencies must support that host.

[workspace]
name = "fpga-example"
channels = ["https://prefix.dev/my-channel"]
platforms = [{ platform = "linux-64", __example_fpga = "1" }]

[dependencies]
fpga-tools = "*"

The platform declaration tells the solver to assume __example_fpga version 1. The detector checks whether your machine actually provides it. We also add the illustrative consumer package fpga-tools, which depends on __example_fpga >= 1, and will thus work for the platform defined at the top of our workspace, but not for a workspace that only supports platforms = ["linux-64"].

From that directory, run:

pixi install

Detectors execute code from the channel. If Pixi asks, choose Trust only if you trust the channel, including its future detectors.

With a supported FPGA, Pixi installs fpga-tools. Without one, installation is rejected because the required __example_fpga >=1 capability is missing.

For more, see Pixi's virtual package detectors and per-platform virtual package requirements docs.