Package Types & Sources

Understanding Package Attributes

Every IVPM package has two fundamental attributes:

Source Type (src): How to fetch the package
Package Type (type): What the package contains

These are independent - any source type can provide any package type.

Source Types

Source types determine how IVPM obtains a package.

Git (`git`)

Clone from a Git repository. Supports branches, tags, commits, and submodules.

Basic usage:

deps:
  - name: my-lib
    url: https://github.com/org/my-lib.git
    src: git  # Usually auto-detected

Attributes:

branch: Checkout a specific branch (default: repository default branch)
tag: Checkout a specific tag
commit: Checkout a specific commit hash
depth: Clone depth for shallow clones (e.g., depth: 1)
anonymous: Use HTTPS instead of SSH (default: false, converts to SSH)
cache: Enable caching (see Caching)

Examples:

# Specific branch
- name: my-lib
  url: https://github.com/org/my-lib.git
  branch: develop

# Specific tag (release)
- name: my-lib
  url: https://github.com/org/my-lib.git
  tag: v1.2.3

# Specific commit
- name: my-lib
  url: https://github.com/org/my-lib.git
  commit: abc123def456

# Shallow clone (faster, less history)
- name: my-lib
  url: https://github.com/org/my-lib.git
  depth: 1

# Anonymous clone (HTTPS, no SSH key needed)
- name: my-lib
  url: https://github.com/org/my-lib.git
  anonymous: true

# Cached (read-only, symlinked from cache)
- name: my-lib
  url: https://github.com/org/my-lib.git
  branch: v1.0
  cache: true

Submodules: Automatically initialized if .gitmodules is present.

URL conversion: By default, HTTPS URLs are converted to SSH format (git@github.com:org/repo.git) unless anonymous: true is set.

PyPI (`pypi`)

Install from the Python Package Index using pip or uv.

Basic usage:

deps:
  - name: requests
    src: pypi

# No URL needed for PyPI packages

Attributes:

version: Version specification (e.g., >=1.0,<2.0)

Examples:

# Latest version
- name: requests
  src: pypi

# Specific version
- name: numpy
  src: pypi
  version: ">=1.20,<2.0"

# Exact version
- name: pytest
  src: pypi
  version: "==7.4.0"

Install behavior: Installed into packages/python/ virtual environment.

npm (`npm`)

Install a package from the npm registry.

Basic usage:

deps:
  - name: lodash
    src: npm

  # With version range
  - name: react
    src: npm
    version: "^18.0.0"

  # Dev-only
  - name: jest
    src: npm
    dev: true

Attributes:

version: npm semver range (e.g., ^18.0.0, >=1.0 <2.0). Defaults to * (latest).
dev: Place in devDependencies. Defaults to false.
optional: Mark as optional. Defaults to false.

Install behavior: Installed into packages/node/node_modules/.

package.json (`package.json`)

Import all dependencies and devDependencies from an existing package.json file into the IVPM-managed Node.js environment. Explicit src: npm entries in the same dep-set take precedence over same-named entries read from the file.

Basic usage:

deps:
  - name: root-pkgjson
    src: package.json
    url: file://${PROJECT_ROOT}/package.json

Attributes:

url: Path to the package.json file (file:// prefix + ${VAR} substitution supported).

Install behavior: Entries are synthesised as src: npm packages and installed into packages/node/node_modules/.

pyproject.toml (`pyproject.toml`)

Import [project].dependencies, optional extras, or PEP 735 dependency-groups from an existing pyproject.toml into the IVPM-managed Python virtual environment. Explicit src: pypi entries in the same dep-set take precedence over same-named entries read from the file.

Basic usage:

deps:
  - name: root-pyproject
    src: pyproject.toml
    url: file://${PROJECT_ROOT}/pyproject.toml

Attributes:

url: Path to the pyproject.toml file (file:// prefix + ${VAR} substitution supported).
include — optional, default: [dependencies]: One section name, a list of section names, or the special value all. Understood names: dependencies, optional-dependencies.<extra>, dependency-groups.<group>. include-group references inside dependency-groups are expanded recursively.

Install behavior: Entries are synthesised as src: pypi packages and installed into packages/python/.

See Python Package Management for full details, examples, and the collision rule.

HTTP/URL (`http`)

Download an archive file via HTTP or HTTPS.

Basic usage:

deps:
  - name: my-package
    url: https://example.com/releases/pkg-1.0.tar.gz
    src: http  # Usually auto-detected

Supported formats:

.tar.gz / .tgz
.tar.xz / .txz
.tar.bz2
.zip
.jar (not unpacked by default)

Attributes:

unpack: Whether to unpack the archive (default: true, except for .jar)
cache: Enable caching (version detected from Last-Modified or ETag)

Examples:

# Download and unpack tarball
- name: boost
  url: https://example.com/boost-1.82.0.tar.gz

# Download JAR (not unpacked)
- name: my-tool
  url: https://example.com/tool.jar
  unpack: false

# Cached download
- name: data-pack
  url: https://cdn.example.com/data.tar.gz
  cache: true

File (`file`)

Use a local file.

Basic usage:

deps:
  - name: local-archive
    url: file:///path/to/package.tar.gz
    src: file  # Usually auto-detected

Examples:

# Absolute path
- name: my-package
  url: file:///home/user/packages/pkg.tar.gz

# With environment variable
- name: my-package
  url: file://${MY_PACKAGE_DIR}/pkg.tar.gz

Directory (`dir`)

Use a local directory. Symlinked or copied into packages/.

Basic usage:

deps:
  - name: local-dev
    url: file:///path/to/source
    src: dir

Attributes:

link: Use symlink (true, default) or copy (false)

Examples:

# Symlink to local development directory
- name: co-developed-lib
  url: file:///home/user/projects/lib
  src: dir
  link: true

# Copy directory contents
- name: template-files
  url: file:///opt/templates
  src: dir
  link: false

Use case: Develop multiple related projects simultaneously.

URL (`url`)

Generic URL source — the fetch method is resolved from the URL extension, just like http, but the src field can be omitted for URLs that IVPM cannot auto-detect as a specific type.

Basic usage:

deps:
  - name: my-package
    url: https://example.com/releases/pkg-1.0.tar.gz
    src: url

Attributes:

cache: Enable caching (see Caching)

Note

In most cases IVPM auto-detects the source type from the URL, so src: url is rarely needed explicitly. It is available as an explicit override when the URL extension is unusual but the content is a standard archive.

GitHub Releases (`gh-rls`)

Download assets from GitHub Releases. Automatically selects platform-specific binaries or falls back to source.

Basic usage:

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

Attributes:

version

Version selector (default: latest)

latest - Most recent non-prerelease
1.2.3 - Exact version (matches tag v1.2.3 or 1.2.3)
>=1.0 - Minimum version
<2.0 - Maximum version (exclusive)
<=1.5 - Maximum version (inclusive)
>1.0 - Greater than version

file

Specific asset filename (not yet implemented)

prerelease

Include pre-release versions (default: false)

source

Force fetching source archive (.tar.gz) instead of platform-specific binary (default: false)

cache

Enable caching (version includes platform info)

Platform selection:

IVPM automatically selects the appropriate asset for your platform:

Linux: manylinux wheels matching your glibc version and architecture
macOS: Assets tagged with “macos”, “darwin”, or “osx”
Windows: Assets tagged with “windows”, “win64”, or “win32”

If no platform-specific binary is found, falls back to source (tarball/zipball).

Examples:

# Latest release
- name: uv
  url: https://github.com/astral-sh/uv
  src: gh-rls

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

# Version range
- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: ">=1.0,<2.0"

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

# Cached
- name: large-binary
  url: https://github.com/org/binary
  src: gh-rls
  cache: true

# Force source download
- name: build-from-source
  url: https://github.com/org/tool
  src: gh-rls
  version: latest
  source: true

Package Types

Package types determine how IVPM processes a package after fetching.

Python (`python`)

Python packages are installed into the project’s virtual environment.

Installation modes:

Editable mode: Source packages with setup.py, setup.cfg, or pyproject.toml are installed with pip install -e
Binary mode: PyPI packages are installed normally

Auto-detection: A package is considered Python if:

src: pypi is specified, OR
Directory contains setup.py, setup.cfg, or pyproject.toml

Examples:

# Source package (editable install)
- name: my-python-lib
  url: https://github.com/org/lib.git
  type: python  # Auto-detected if setup.py exists

# PyPI package
- name: requests
  src: pypi  # Automatically type: python

Type-specific parameters ( with: ):

When type: python is specified you can pass additional parameters under a with: key to control how the package is installed:

editable (boolean, default: true): Install the source package in editable mode (pip install -e). Set to false to install as a regular (non-editable) package.
extras (string or list of strings): PEP 508 extras to request when installing (e.g. [tests], [litellm, openai]).

# Non-editable install
- name: my-lib
  url: https://github.com/org/my-lib.git
  type: python
  with:
    editable: false

# Source package with extras
- name: my-lib
  url: https://github.com/org/my-lib.git
  type: python
  with:
    extras: [tests, docs]

# Non-editable with extras
- name: my-lib
  url: https://github.com/org/my-lib.git
  type: python
  with:
    extras: [tests]
    editable: false

Note

with: is only valid when type: is also specified on the same entry. Unknown keys inside with: are a validation error. Parameter validation happens at YAML-read time, before any packages are fetched.

Note

When a package has type: python (explicitly or via auto-detection), the Python handler installs it into packages/python/ during the root phase of every update / clone run. See Python Handler (python) in Package Handlers for the full list of installation options and CLI flags such as --py-uv and --force-py-install.

Node (`node`)

Node.js packages are installed into the project’s Node.js environment at packages/node/.

Auto-detection: A package is considered Node.js if:

src: npm is specified, OR
Directory contains package.json

Examples:

# npm registry package
- name: lodash
  src: npm

# Source package with package.json (auto-detected)
- name: my-ts-lib
  url: https://github.com/org/my-ts-lib.git
  type: node

Note

When a package has type: node, the Node handler installs it into packages/node/ during the root phase. See Node Handler (node) in Package Handlers for the full list of options, and Node.js Package Management for complete Node.js workflow details.

Raw (`raw`)

Raw packages are placed in packages/<name>/ but not processed further.

Use cases:

Data files
Configuration
IP cores (Verilog, VHDL)
Documentation
Pre-built binaries

Examples:

# Verilog IP
- name: uart-rtl
  url: https://github.com/org/uart.git
  type: raw

# Test data
- name: test-vectors
  url: https://example.com/vectors.tar.gz
  type: raw

Note

type: raw accepts no with: parameters. This type is also useful to suppress Python auto-detection on a package that happens to contain a pyproject.toml but should not be pip-installed.

Note

Packages with type: raw are intentionally not processed by any built-in handler — they are simply placed in packages/<name>/ and left as-is. This is the right choice for IP cores, data files, and pre-built binaries that need no install step.

ivpm.yaml (Dep-Set Factory)

A src: ivpm.yaml dependency is a dep-set factory: it reads a referenced ivpm.yaml, selects one of its dep-sets, and folds those packages into the consuming dep-set. Unlike every other source, a factory installs no content of its own — it has no packages-dir representation. It is purely a source of dependency definitions.

package:
  name: my-pkg
  dep-sets:
    - name: default
      deps:
        - name: core-tools
          src: ivpm.yaml
          url: https://example.com/tools.yaml   # http(s) or local path
          dep-set: core                         # which dep-set to pull

The deps defined in the referenced file’s core dep-set are resolved and pinned exactly as if they had been written directly in the consumer’s default dep-set. Each is recorded with resolved_by set to the factory dependency’s name.

Fields

url (required) — http(s) URL or a local path (file:// or relative) of the factory ivpm.yaml. Relative paths resolve against the file that declares the dependency.
dep-set (optional) — the dep-set to pull from the factory. Defaults to the consuming dep-set’s name.

No packages-dir representation. The factory is a virtual node: nothing is checked out under packages/ for it, and it does not appear in ivpm status or ivpm sync (it has no working tree to act on). What is tracked lives in Package Lock File:

Each contributed leaf gets a from_ivpm_source: "<url>#<dep-set>" provenance field on its package-lock entry.
The factory itself is recorded under a top-level ivpm_sources map keyed by url, with the dep-set name and a resolved fingerprint (etag / last-modified, else a content sha256). This lets a re-resolve detect that the factory’s dep-set membership changed upstream, even though each leaf re-pins independently.

Transitive factories and cycles. A factory’s dep-set may itself contain src: ivpm.yaml deps; these are expanded recursively. A factory that (transitively) references its own url is a fatal cyclic reference.

Fetch protocols (v1). http(s) and local paths are supported. Git-URL factories (a dep-set pulled directly from a repository) are not yet supported.

Note

include: (see Splitting ivpm.yaml Across Files) and src: ivpm.yaml are complementary: include: composes files on the local filesystem into one package definition, while src: ivpm.yaml consumes a dep-set published elsewhere as an ordinary dependency.

Auto-Detection

IVPM automatically detects both source and package types.

Source Type Auto-Detection

Based on the URL:

URL Pattern	Detected Source Type
Ends with `.git`	`git`
Starts with `http://` or `https://`	`http`
Starts with `file://` (is a file)	`file`
Starts with `file://` (is a directory)	`dir`
No URL specified	`pypi`

Package Type Auto-Detection

Based on content and source:

Condition	Detected Package Type
`src: pypi`	`python`
Contains `setup.py`, `setup.cfg`, or `pyproject.toml`	`python`
`src: npm`	`node`
Contains `package.json`	`node`
Otherwise	`raw`

When to Specify Explicitly

Specify source or package type explicitly when:

Auto-detection is wrong

# URL doesn't end in .git but is a Git repo
- name: repo
  url: https://git.example.com/repo
  src: git

You want different behavior

# Has setup.py but want to treat as raw
- name: data-package
  url: https://github.com/org/data.git
  type: raw

Using gh-rls (always specify)

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

Common Dependency Patterns

Pattern 1: Mix of Sources

deps:
  # Git source (editable Python package)
  - name: my-library
    url: https://github.com/org/library.git

  # PyPI binary
  - name: numpy
    src: pypi
    version: ">=1.20"

  # HTTP archive (raw data)
  - name: test-data
    url: https://cdn.example.com/data.tar.gz
    type: raw

  # Local development
  - name: co-dev-lib
    url: file:///home/user/projects/lib
    src: dir

Pattern 2: Versioned Dependencies

deps:
  # Git tag
  - name: stable-lib
    url: https://github.com/org/lib.git
    tag: v2.0.0

  # Git commit (for reproducibility)
  - name: exact-version
    url: https://github.com/org/exact.git
    commit: abc123def456

  # PyPI version
  - name: requests
    src: pypi
    version: "==2.28.0"

  # GitHub Release version
  - name: tool
    url: https://github.com/org/tool
    src: gh-rls
    version: ">=1.0,<2.0"

Pattern 3: Cached Dependencies

deps:
  # Cached Git (read-only, symlinked)
  - name: large-repo
    url: https://github.com/org/large.git
    branch: stable
    cache: true

  # Cached HTTP (read-only, symlinked)
  - name: big-archive
    url: https://cdn.example.com/big.tar.gz
    cache: true

  # Cached GitHub Release (platform-specific)
  - name: binary-tool
    url: https://github.com/org/tool
    src: gh-rls
    cache: true

Complete Reference

All Package Attributes

Attribute	Type	Description
`name`	string	Package identifier (required)
`url`	string	Source URL (not needed for pypi)
`src`	string	Source type: git, pypi, http, file, dir, gh-rls
`type`	string	Package type: python, raw
`version`	string	Version spec (PyPI, gh-rls)
`branch`	string	Git branch
`tag`	string	Git tag
`commit`	string	Git commit hash
`depth`	integer	Git clone depth
`anonymous`	boolean	Use HTTPS for Git
`cache`	boolean	Enable caching
`deps`	string	“skip” to skip sub-dependencies
`dep-set`	string	Sub-package dependency set
`link`	boolean	Symlink (true) or copy (false) for dir
`unpack`	boolean	Unpack archives
`file`	string	GitHub Release asset filename
`prerelease`	boolean	Include GitHub prereleases
`source`	boolean	Force source archive for gh-rls

Package Types & Sources

Understanding Package Attributes

Source Types

Git (git)

PyPI (pypi)

npm (npm)

package.json (package.json)

pyproject.toml (pyproject.toml)

HTTP/URL (http)

File (file)

Directory (dir)

URL (url)

GitHub Releases (gh-rls)

Package Types

Python (python)

Node (node)

Raw (raw)

ivpm.yaml (Dep-Set Factory)

Auto-Detection

Source Type Auto-Detection

Package Type Auto-Detection

When to Specify Explicitly

Common Dependency Patterns

Pattern 1: Mix of Sources

Pattern 2: Versioned Dependencies

Pattern 3: Cached Dependencies

Complete Reference

All Package Attributes

See Also

Git (`git`)

PyPI (`pypi`)

npm (`npm`)

package.json (`package.json`)

pyproject.toml (`pyproject.toml`)

HTTP/URL (`http`)

File (`file`)

Directory (`dir`)

URL (`url`)

GitHub Releases (`gh-rls`)

Python (`python`)

Node (`node`)

Raw (`raw`)