Getting Started with IVPM

Installing IVPM

IVPM must be installed before it can be used to work with a project. Typically, the easiest approach is to install IVPM as a user-installed package:

$ python3 -m pip install --user ivpm

Once this is done, you can invoke IVPM either via the entry-point script (ivpm) or as a Python module:

$ ivpm --help
$ python3 -m ivpm --help

Quick Start: Clone an Existing Project

The fastest way to start with IVPM is to clone an existing IVPM-enabled project:

$ ivpm clone https://github.com/org/project.git
$ cd project

This single command:

  1. Clones the Git repository

  2. Reads the project’s ivpm.yaml

  3. Fetches all dependencies

  4. Creates a Python virtual environment

  5. Installs Python packages

After cloning, you’re ready to work:

$ ivpm activate -c "python --version"
$ ivpm activate -c "pytest"

Clone Command Options

$ ivpm clone [options] <src-url-or-path> [workspace_dir]

Common options:

-a, --anonymous

Clone anonymously over HTTPS instead of using SSH. By default, HTTPS URLs are converted to SSH form (git@host:path).

-b, --branch <name>

Checkout the specified branch. If origin/<name> exists, it will be checked out tracking the remote; otherwise, a new local branch is created.

-d, --dep-set <name>

Specify the dependency set for ivpm update (e.g., default-dev).

--py-uv or --py-pip

Choose whether ivpm update should use “uv” or “pip” to manage the project-local Python virtual environment.

--py-system-site-packages

Opt in to inheriting system site-packages inside the virtual environment. By default the environment is isolated; use this flag only when you need access to system-installed packages (e.g. hardware-specific bindings).

Examples:

# Clone with default workspace directory name
$ ivpm clone https://github.com/fvutils/ivpm

# Clone into specific directory with new branch
$ ivpm clone https://github.com/org/project my-workspace -b feature/new

# Clone anonymously and select dependency set
$ ivpm clone -a https://github.com/org/project -d default-dev

# Clone and use uv for Python package management
$ ivpm clone https://github.com/org/project --py-uv

Creating a New IVPM Project

Step 1: Initialize the Project

$ mkdir my-project
$ cd my-project
$ ivpm init my-project -v 0.1.0

This creates a basic ivpm.yaml file:

package:
  name: my-project
  version: "0.1.0"

JSON Schema Support

For IDE autocompletion and validation, add a $schema reference at the top of your ivpm.yaml:

$schema: https://fvutils.github.io/ivpm/ivpm.schema.json

package:
  name: my-project
  version: "0.1.0"

Step 2: Add Dependency Sets

Edit ivpm.yaml to add your dependencies:

$schema: https://fvutils.github.io/ivpm/ivpm.schema.json

package:
  name: my-project
  version: "0.1.0"
  default-dep-set: default-dev

  dep-sets:
    - name: default
      deps:
        - name: requests
          src: pypi

    - name: default-dev
      uses: default
      deps:
        - name: pytest
          src: pypi

For details on dependency sets, see Dependency Sets.

Step 3: Run Initial Update

Fetch dependencies and create the Python virtual environment:

$ ivpm update

This creates:

my-project/
├── ivpm.yaml
└── packages/
    └── python/           # Virtual environment
        ├── bin/
        ├── lib/
        └── ...

Step 4: Work with Your Project

# Run a command in the virtual environment
$ ivpm activate -c "pytest"

# Start an interactive shell
$ ivpm activate
(venv) $ python
(venv) $ exit

Using the Python Virtual Environment

IVPM creates a project-local Python virtual environment in packages/python/.

Run a single command:

$ ivpm activate -c "python script.py"
$ ivpm activate -c "pytest"

Start an interactive shell:

$ ivpm activate
(venv) $ python
(venv) $ pytest
(venv) $ exit

For details on Python package management (editable installs, uv vs pip, native extensions), see Python Package Management.

Next Steps

Now that you have the basics: