# The Supervisely SDK computes its own version by walking git history

> A computer vision platform with a Python SDK, five levels of integration and an app ecosystem. The packaging is where the interesting engineering is, and it has a gap you can hit without warning.

**supervisely/supervisely** — Supervisely SDK for Python - convenient way to automate, customize and extend Supervisely Platform for your computer vision task 

- Repository: https://github.com/supervisely/supervisely
- Website: https://supervisely.com
- Stars: 544 · Forks: 78
- Language: Python
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/supervisely-supervisely

## The version number is computed by walking git history

The packaging file does something unusual before it declares anything. It first checks an environment variable for a release version and returns it immediately if set. Failing that, it asks git which branch it is on, then makes a network request to the GitHub releases API for this repository, then computes the merge base between the current commit and the default branch. From that merge base it walks forward commit by commit, collecting the tags that point at each one, and cross-references those tags against the releases the API returned. The version is whatever release that resolves to. So the number is a function of git topology plus a live network call, evaluated while the package builds. The practical consequences are concrete: a build inside a container with no git metadata cannot compute a version, and neither can an install from a source distribution that shipped without its history. The environment variable is the documented escape hatch.

## setuptools is pinned twice, with a gap between the ranges

The build requirements contain four entries, and two of them constrain the same package under different conditions. On Python 3.10 and newer, setuptools is required at 83 or later and below 84. On anything older, setuptools is required below 76. Wheel is required outright. And an HTTP client is listed as a build requirement, which is unusual and is there because the version walker needs to make that request. The two setuptools ranges do not touch. There is no interpreter version for which a resolver is permitted to pick a setuptools between 76 and 83, so any build environment that lands in that hole fails rather than silently choosing something. That may be intentional if a regression in a middle version forced the split, but nothing in the file says so. The distinction to keep straight is that this is the build-time toolchain; the same file also imports a packaging library at runtime to read distribution metadata and to find packages, which is a separate concern from what the build requires.

## Five levels of integration, and the SDK is only the second

The platform describes integration as five rungs rather than one API. The first is an HTTP interface that covers basically every action available through the user interface, and it is explicitly language-agnostic: any programming language and any development environment. The second is Python scripts for automation and integration, and this is where the SDK sits, with a recommendation to Python developers to use it rather than the interface underneath it. The third is headless apps with no user interface. The fourth is apps with interactive interfaces of their own. The fifth is apps whose interface is integrated into the labeling tools themselves, which is the deepest coupling and the one that lets a tool appear inside the workflow rather than beside it. The consequence is that the SDK is a convenience layer over an interface that is nominally complete, not the only way in. That matters if your stack is not Python, because nothing in the design requires you to adopt the SDK.

## An app is a web server, and the operating system framing depends on it

The central architectural claim is that an app is just a web server, and you can use any technology you prefer. That single sentence is what makes the rest of the design coherent. The platform is described as an operating system available through a web browser, and development is framed the same way a desktop operating system would be. The ecosystem of applications is compared to an app store, where the expectation is that something exists for every task and installing it is a single click in the browser. If an app were a plugin loaded into the host process, none of that would follow. As a web service, an app can be written in any language, deployed independently, and mounted at the same time as hundreds of others, which is what makes a single-click ecosystem plausible. The cost of the choice is that every app carries its own runtime, its own dependencies and its own deployment story.

## Three releases in four days, each naming a user-visible change

The release cadence is tight and the titles describe what a user will notice. The newest adds audio projects with SDK support, spectrogram settings and import. The one before it changes the editor so it stays scrollable after an edit, and names the frontend bundle version it carries. The third adds support for a telemetry labeling interface, and lands on the same day as the editor change. Two releases on one day and three across four is a normal rate for a platform shipping continuously rather than in versions you plan around. One detail in the titles is telling: a release of the Python SDK names a frontend bundle version, which tells you the two ship together and that an SDK upgrade can drag a user interface change along with it. The fourth component of the version is already in the forties, which tells you the same thing from the other direction.

## Audio reached the SDK before it reached the feature list

The platform capability list in the documentation covers labeling for images, videos, three-dimensional point clouds and volumetric medical images, plus visualization and quality control, pretrained models for segmentation, detection and classification, interactive performance analysis tools, models specialised for accelerating labeling, synthetic data generation, and collaboration instruments for the mix of data scientists, labelers, domain experts and engineers. Audio is not on that list. The newest release adds audio projects with spectrogram settings and import, which means the documentation's capability enumeration lags the release notes by at least one release cycle. That is a small thing and a normal one, but it is worth knowing before you read a feature list as a boundary. Anything you need to confirm exists should be checked against the release notes rather than the overview page.

## Two near-identically named packages and a shell script for setup

The repository root carries two package directories whose names differ only by an underscore and a word, plus a command line directory and a shell script for creating a virtual environment. Alongside them sit two separate linter configurations, one for style checking and one for the broader static pass, a documentation build configuration, a container ignore file, and two directories for base images and built images. The dual package layout is the part that will slow you down: a reader looking for where the SDK code lives has to determine which of the two directories is the distribution and which is a shared library the other imports. The shell script next to a modern pyproject file is the residue of the same transition, since the packaging metadata was modernised and the environment bootstrap was not. None of this is wrong, and all of it is the shape of a project that has been restructured without deleting the old path.

## Conclusion

Use Supervisely if you want computer vision infrastructure that already handles labeling, quality control and model serving rather than assembling it yourself, and if being able to write an app in any language matters to you. Before you adopt the SDK as a dependency, understand that it is not a static artifact: the version is computed at build time from git history and a live query to the GitHub API, so offline builds and source tarballs are a problem. Confirm which parts are open, since the SDK carries an Apache 2.0 licence with public source while the platform itself is a hosted browser product.

## FAQ

### what is supervisely

A computer vision platform, described as an operating system available through a web browser, covering data labeling for images, videos, 3D point clouds and volumetric medical images, plus visualization, quality control, pretrained models, synthetic data generation and a marketplace of apps. The Python SDK is the automation layer over it.

### is supervisely open source

The SDK carries an Apache 2.0 licence and its source is published on GitHub. The documentation also states the platform is trusted by large enterprises and used by tens of thousands of researchers and developers, so the SDK being open does not mean the hosted platform is.

### How do I install the Supervisely SDK?

From the package index with pip. The repository also ships a script for creating a virtual environment, plus separate directories for base and built container images, so a containerised install is also supported.

### What are the five levels of Supervisely integration?

An HTTP interface usable from any language, Python scripts for automation, headless apps with no interface, apps with their own interactive interfaces, and apps whose interfaces are integrated into the labeling tools. The Python SDK sits at the second level.

### How does the Supervisely SDK compute its version number?

At build time. It reads an environment variable if set, otherwise asks git for the branch, queries the GitHub releases API, computes the merge base with the default branch, and walks forward collecting tags until one matches a published release.

### Do I have to use the Python SDK to build on Supervisely?

No. The lowest integration level is an HTTP interface covering essentially every action available through the user interface, usable from any programming language and environment. An app is also described as just a web server in any technology you prefer.

## Sources

- [License: Apache-2.0](https://github.com/supervisely/supervisely/blob/master/LICENSE)
- [Project website](https://supervisely.com)
- [README](https://github.com/supervisely/supervisely/blob/master/README.md)
- [Releases](https://github.com/supervisely/supervisely/releases)
- [supervisely/supervisely on GitHub](https://github.com/supervisely/supervisely)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/supervisely-supervisely