GitHub Releases

Overview

IVPM can automatically download and install packages from GitHub Releases, including platform-specific binaries. This is ideal for:

Pre-built tools and utilities
Platform-specific executables
Large binary distributions
Versioned releases without full Git history

IVPM automatically selects the appropriate binary for your platform (Linux, macOS, Windows) or falls back to source archives.

Basic Usage

Simple Example

deps:
  - name: uv
    url: https://github.com/astral-sh/uv
    src: gh-rls

This downloads the latest release of uv for your platform.

With Version

deps:
  - name: ruff
    url: https://github.com/astral-sh/ruff
    src: gh-rls
    version: "0.1.0"

Cached

deps:
  - name: tool
    url: https://github.com/org/tool
    src: gh-rls
    cache: true

Cached packages are stored by release tag and platform: <tag>_<platform>_<arch>.

Version Selection

IVPM supports multiple version selection strategies:

Latest Release

# Latest stable release (default)
- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: latest

Excludes pre-releases by default. To include pre-releases:

- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: latest
  prerelease: true

Exact Version

Match an exact release tag:

# Matches tag 'v1.2.3' or '1.2.3'
- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: "1.2.3"

# Also works with 'v' prefix
- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: "v1.2.3"

Version Range

Use comparison operators:

# Minimum version
- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: ">=1.0.0"

# Maximum version (exclusive)
- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: "<2.0"

# Maximum version (inclusive)
- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: "<=1.5.0"

# Greater than
- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: ">1.0"

Behavior:

>= and > select the earliest matching version
<= and < select the latest matching version

Examples:

Given releases: v1.0.0, v1.1.0, v1.2.0, v2.0.0

>=1.1.0 → selects v1.1.0
<2.0 → selects v1.2.0
>1.0.0 → selects v1.1.0
<=1.2.0 → selects v1.2.0

Version Parsing

IVPM parses version tags flexibly:

v1.2.3 → (1, 2, 3)
1.2.3 → (1, 2, 3)
v1.2 → (1, 2)
1.2.3.4 → (1, 2, 3, 4)

Comparison is done numerically on each component.

Pre-release Handling

By default, pre-releases are excluded:

- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: latest  # Excludes alpha, beta, rc

To include pre-releases:

- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: latest
  prerelease: true

This affects all version selectors:

# Include prereleases in version range
- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: ">=1.0.0"
  prerelease: true

Platform Selection

IVPM automatically detects your platform and selects the appropriate binary asset.

Supported Platforms

Linux:

Detects glibc version
Matches manylinux wheels (manylinux_2_17_x86_64, etc.)
Matches generic Linux binaries (linux-x86_64, linux-aarch64, etc.)
Supported architectures: x86_64, aarch64, armv7l

macOS:

Detects architecture (x86_64, arm64)
Matches assets with “macos”, “darwin”, or “osx”
Universal binaries supported

Windows:

Matches assets with “windows”, “win64”, “win32”
Supported architectures: x86_64, x86

Platform Detection Examples

Linux x86_64 with glibc 2.31:

IVPM looks for:

manylinux_2_31_x86_64 (exact match)
manylinux_2_28_x86_64 (older compatible)
manylinux_2_17_x86_64 (manylinux2014)
Generic linux-x86_64 or linux_x86_64 binaries
Falls back to source

macOS arm64 (M1/M2):

IVPM looks for:

Assets with “arm64” or “aarch64” and “macos”/”darwin”/”osx”
Falls back to any macOS asset
Falls back to source

Windows x86_64:

IVPM looks for:

Assets with “x86_64” or “amd64” and “windows”/”win64”/”win”
Falls back to any Windows asset
Falls back to source

Linux Binary Naming Schemes

IVPM supports two Linux binary naming schemes:

1. manylinux Tags (Preferred for Python wheels and glibc-aware packages):

Tag	glibc Version	Compatible Systems
manylinux1	2.5	Very old systems
manylinux2010	2.12	CentOS 6+
manylinux2014	2.17	CentOS 7+
manylinux_2_28	2.28	Ubuntu 22.04+
manylinux_2_31	2.31	Recent systems

IVPM selects the newest compatible manylinux version for your system.

2. Generic Linux Naming (Common for C/C++ tools like protobuf):

IVPM also recognizes generic Linux binary naming patterns:

linux-x86_64 or linux_x86_64
linux-aarch64 or linux_aarch64 or linux-arm64
linux-aarch_64 (protobuf style)

Examples:

protoc-33.2-linux-x86_64.zip
tool-v1.0-linux-aarch64.tar.gz
binary-linux_x86_64.tar.xz

Selection Priority:

IVPM first looks for manylinux-tagged assets (glibc-aware)
If none found, falls back to generic Linux naming patterns
If neither found, falls back to source archives

Source Fallback

If no platform-specific binary is found, IVPM falls back to source archives:

Try tarball_url (typically .tar.gz)
Try zipball_url (typically .zip)
Try any single generic asset
Fail with helpful error message

Example:

If a release has:

Source: source.tar.gz
Windows: tool-windows.zip
Linux: tool-linux.tar.gz
macOS: tool-macos.tar.gz

On FreeBSD (unsupported), IVPM will download source.tar.gz.

Forcing Source Download

You can force IVPM to download the source archive instead of platform-specific binaries using the source option:

deps:
  - name: tool
    url: https://github.com/org/tool
    src: gh-rls
    version: latest
    source: true

This is useful when:

You want to build from source for optimization or customization
Binary releases don’t work on your platform
You need to audit or modify the source code
You’re distributing to users who will build themselves

When source: true is set:

IVPM skips all platform binary detection
Downloads tarball_url (GitHub’s source tarball, typically .tar.gz)
Falls back to zipball_url if tarball not available
Extracts to your packages directory

Complete Examples

Example 1: Installing uv

deps:
  - name: uv
    url: https://github.com/astral-sh/uv
    src: gh-rls
    version: latest

What happens:

Queries GitHub API for latest release
Detects your platform (e.g., Linux x86_64 glibc 2.31)
Selects uv-x86_64-unknown-linux-gnu.tar.gz
Downloads and extracts to packages/uv/

Usage:

$ ivpm update
$ packages/uv/uv --version

Example 2: Specific Version with Cache

deps:
  - name: ruff
    url: https://github.com/astral-sh/ruff
    src: gh-rls
    version: "0.1.6"
    cache: true

What happens:

Finds release with tag v0.1.6 or 0.1.6
Selects platform-specific binary
Caches with key 0.1.6_linux_x86_64 (example)
Symlinks from cache to packages/ruff/

Benefits:

Shared across projects
Instant for subsequent projects
Different platforms cache separately

Example 3: Version Range

deps:
  - name: tool
    url: https://github.com/org/tool
    src: gh-rls
    version: ">=1.2.0,<2.0"

Interpretation: Not directly supported as a single string.

Workaround: Use simple comparator:

# Get earliest >= 1.2.0
- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: ">=1.2.0"

Example 4: Including Prereleases

deps:
  - name: beta-tool
    url: https://github.com/org/tool
    src: gh-rls
    version: latest
    prerelease: true

What happens:

Queries all releases including pre-releases
Selects most recent (could be beta, rc, etc.)
Downloads platform-specific asset

Example 5: Protocol Buffers

deps:
  - name: protobuf
    url: https://github.com/protocolbuffers/protobuf
    src: gh-rls
    version: latest

What happens:

Queries GitHub API for latest release
Detects your platform (e.g., Linux x86_64)
Selects protoc-33.2-linux-x86_64.zip (generic Linux naming)
Downloads and extracts to packages/protobuf/

Usage:

$ ivpm update
$ packages/protobuf/bin/protoc --version
libprotoc 33.2

This demonstrates IVPM’s support for generic Linux binary naming (not manylinux).

Example 6: Forcing Source Download

deps:
  - name: verilator
    url: https://github.com/verilator/verilator
    src: gh-rls
    version: latest
    source: true

What happens:

Queries GitHub API for latest release
Skips all binary detection (even if binaries are available)
Downloads source tarball (tarball_url)
Extracts to packages/verilator/

Use case:

Building Verilator from source for custom optimization flags or when pre-built binaries aren’t compatible with your system.

Example 7: Mixed Binaries and Source

package:
  name: verification-suite
  dep-sets:
    - name: default-dev
      deps:
        # Binary tool
        - name: verilator-bin
          url: https://github.com/verilator/verilator
          src: gh-rls
          version: latest
          cache: true

        # Source package
        - name: cocotb
          src: pypi

        # Git source
        - name: uvm-python
          url: https://github.com/pyuvm/pyuvm.git

Troubleshooting

No Suitable Binary Found

Error: No suitable <platform> binary found

Causes:

Release doesn’t have a binary for your platform
Asset naming doesn’t match IVPM’s detection
Your glibc is too old (Linux)

Solutions:

Check available assets:

Visit the GitHub release page and see what’s available.
Use source fallback:

If IVPM can’t find a binary, it should fall back to source. If this fails, check if tarball_url or zipball_url exists.

Build from source:

# Switch to Git source
- name: tool
  url: https://github.com/org/tool.git
  branch: v1.0.0

glibc Version Too New

Error: Binary requires newer glibc

Check your glibc:

$ ldd --version
ldd (GNU libc) 2.31

Solution:

Upgrade your system
Use older release
Build from source

No Release Found

Error: Failed to find latest release or No release matches version spec

Causes:

Repository has no releases
All releases are pre-releases (and prerelease: false)
Version spec doesn’t match any release

Solutions:

Check releases exist:

Visit https://github.com/org/repo/releases

Enable prereleases:

- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  prerelease: true

Adjust version spec:

# Too specific
version: "1.0.0"

# More flexible
version: ">=1.0"

Rate Limiting (GitHub API)

Error: HTTP 403 or rate limit message

Cause: GitHub API rate limits (60 requests/hour for unauthenticated)

Solution:

Set GITHUB_TOKEN environment variable:

export GITHUB_TOKEN=ghp_your_token_here
ivpm update

Get a token from: https://github.com/settings/tokens

Asset Naming Issues

Problem: IVPM doesn’t detect your platform’s binary

Cause: Asset naming doesn’t match IVPM’s patterns

Example release assets:

tool-1.0-linux64.tar.gz ← Not detected (needs more specific pattern)
tool-1.0-linux-x86_64.tar.gz ← Detected (generic Linux)
tool-1.0-manylinux_2_17_x86_64.tar.gz ← Detected (manylinux)
tool-1.0-macosx.tar.gz ← Detected (has “mac”)
tool-1.0.tar.gz ← Used as fallback source

Supported naming patterns:

Linux: manylinux_X_Y_arch, manylinux2014_arch, linux-arch, linux_arch
macOS: macos, darwin, osx with optional x86_64, arm64, aarch64
Windows: windows, win64, win32, win with optional x86_64, amd64

Workaround:

Contact package maintainer to use standard naming patterns listed above.

Best Practices

Cache binary releases - They’re large and don’t change
Pin versions in production - Use exact versions for reproducibility
Use version ranges in development - Stay updated with >=1.0
Check release assets - Verify binaries exist for your platform before configuring
Set GITHUB_TOKEN - Avoid rate limiting in CI/CD
Test on all platforms - Ensure assets exist for Linux, macOS, Windows if deploying cross-platform
Document platform requirements - Let users know if only certain platforms are supported
Provide source fallback - Ensure releases include source archives

Advanced Configuration

Forcing Source Archives

Use source: true to skip platform binary selection and download source:

- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: "1.0.0"
  source: true

This downloads the GitHub source tarball (.tar.gz) or zipball (.zip) instead of platform-specific binaries.

Benefits:

Full source code access for building with custom flags
Avoid binary compatibility issues
Works on any platform (not just those with prebuilt binaries)

Tradeoffs:

Requires build tools and dependencies to be installed
Slower initial setup compared to downloading prebuilt binaries
May need manual build steps after download

Specific Asset File (Not Yet Implemented)

Future support for selecting specific asset:

- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: "1.0.0"
  file: "tool-custom-x86_64.tar.gz"

Currently, IVPM auto-selects based on platform.

Custom URL Patterns

For non-standard release URLs, use http source type:

- name: tool
  url: https://github.com/org/tool/releases/download/v1.0/tool.tar.gz
  src: http

GitHub Releases

Overview

Basic Usage

Simple Example

With Version

Cached

Version Selection

Latest Release

Exact Version

Version Range

Version Parsing

Pre-release Handling

Platform Selection

Supported Platforms

Platform Detection Examples

Linux Binary Naming Schemes

Source Fallback

Forcing Source Download

Complete Examples

Example 1: Installing uv

Example 2: Specific Version with Cache

Example 3: Version Range

Example 4: Including Prereleases

Example 5: Protocol Buffers

Example 6: Forcing Source Download

Example 7: Mixed Binaries and Source

Troubleshooting

No Suitable Binary Found

glibc Version Too New

No Release Found

Rate Limiting (GitHub API)

Asset Naming Issues

Best Practices

Advanced Configuration

Forcing Source Archives

Specific Asset File (Not Yet Implemented)

Custom URL Patterns

See Also