vix install

vix install installs Vix Registry dependencies.

Use it when you want to install the exact dependencies pinned in vix.lock, generate CMake integration files, or install one package globally.

bash

vix install

Overview

vix install has two modes:

txt

project mode
global mode

1
2

Project mode installs dependencies for the current project:

bash

vix install

Global mode installs one package globally:

bash

vix install -g gk/jwt

The command is part of the Vix Registry workflow.

It connects:

txt

vix.json
vix.lock
registry index
global package store
project .vix/deps
.vix/vix_deps.cmake
vix.app
CMake

1
2
3
4
5
6
7
8

Usage

bash

vix install
vix install -g <package>
vix install --global <package>

1
2
3

Basic examples

bash

# Install project dependencies from vix.lock
vix install

# Install a global package
vix install -g gk/jwt

# Install a specific global version
vix install -g gk/jwt@1.0.0

# Install with a semver range
vix install -g gk/jwt@^1.0.0

# Scoped-style syntax is also accepted
vix install -g @gk/jwt
vix install -g @gk/jwt@~1.2.0

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

What it does

Mode	Command	Purpose
Project mode	`vix install`	Install exact project dependencies from `vix.lock`.
Global mode	`vix install -g <pkg>`	Resolve and install one package globally.

Project mode

Run:

bash

vix install

Project mode reads:

txt

vix.lock

Then it installs the exact locked dependencies. It does not choose new versions. It does not rewrite dependency ranges. It does not behave like vix update.

The main purpose is reproducibility:

txt

same vix.lock
same dependency versions
same commits
same install result

1
2
3
4

Project install outputs

A project install can create:

txt

.vix/
├── deps/
│   └── ...
└── vix_deps.cmake

1
2
3
4

Important outputs:

Path	Purpose
`.vix/deps/`	Project-local links or copies of installed packages.
`.vix/vix_deps.cmake`	Generated CMake integration for dependencies.

Do not edit:

txt

.vix/vix_deps.cmake

It is generated by Vix.

Global mode

Run:

bash

vix install -g gk/jwt

or:

bash

vix install --global gk/jwt

Global mode resolves one package from the registry, fetches it, stores it globally, and records it in the global installed manifest.

Typical outputs:

txt

~/.vix/global/packages/
~/.vix/global/installed.json

1
2

Global install is useful when you want a package available outside one specific project.

Global install syntax

Accepted package forms:

txt

namespace/name
namespace/name@version
namespace/name@range
@namespace/name
@namespace/name@version
@namespace/name@range

1
2
3
4
5
6

Examples:

bash

vix install -g gk/jwt
vix install -g gk/jwt@1.0.0
vix install -g gk/jwt@^1.0.0
vix install -g @gk/jwt
vix install -g @gk/jwt@~1.2.0

1
2
3
4
5

Version resolution

When a package version is not provided, Vix selects the latest available version from the registry.

bash

vix install -g gk/jwt

When a version range is provided, Vix resolves the highest version that satisfies the range.

bash

vix install -g gk/jwt@^1.0.0

Supported range forms include common semver-style inputs such as:

txt

1.2.3
^1.2.3
~1.2.3
>=1.0.0
<=2.0.0
>1.0.0
<2.0.0
*
latest

1
2
3
4
5
6
7
8
9

Registry requirement

vix install needs the local registry index.

If the registry has not been synced, Vix reports:

txt

registry not synced
Run: vix registry sync

1
2

Fix:

bash

vix registry sync
vix install

1
2

For global install:

bash

vix registry sync
vix install -g gk/jwt

1
2

Project install workflow

For a new project:

bash

vix new api
cd api
vix install
vix dev

1
2
3
4

For an existing project:

bash

git clone https://github.com/example/api.git
cd api
vix install
vix dev

1
2
3
4

For CI:

bash

vix install
vix build --build-target all
vix tests

1
2
3

Registry dependency workflow

Use vix add when adding a new dependency.

bash

vix add gk/json@^1.0.0

Then install:

bash

vix install

A normal dependency workflow is:

bash

vix registry sync
vix add gk/json@^1.0.0
vix install
vix build

1
2
3
4

Difference between `vix add` and `vix install`

Command	Purpose
`vix add <pkg>`	Add a dependency to the project and update dependency metadata.
`vix install`	Install dependencies already pinned in `vix.lock`.

Use vix add when you want to add something new.

Use vix install when the lockfile already exists and you want to install what it says.

Difference between `vix update` and `vix install`

Command	Purpose
`vix update`	Resolve newer versions and rewrite `vix.lock`.
`vix install`	Install exact versions already pinned in `vix.lock`.

Use vix update when you want newer dependency versions.

Use vix install when you want reproducible locked versions.

Difference between project and global install

Mode	Stores packages in	Uses `vix.lock`	Generates `.vix/vix_deps.cmake`
Project install	`.vix/deps/` and global store checkout cache	yes	yes
Global install	`~/.vix/global/packages/`	no	no

Project install is for building a project.

Global install is for installing one package globally.

Package cache

Vix stores fetched Git checkouts under:

txt

~/.vix/store/git/

A package checkout is stored by package identity and commit.

This means repeated installs can reuse existing package checkouts.

The project then receives links or copies under:

txt

.vix/deps/

This keeps project installs fast while keeping dependency state reproducible.

Integrity checks

If a dependency in vix.lock contains a hash, Vix can verify the checkout content.

If the hash does not match, Vix reports an integrity failure.

Example shape:

txt

integrity check failed: gk/json
expected: ...
actual:   ...

1
2
3

This protects the install from using unexpected dependency contents.

Generated CMake integration

Project install generates:

txt

.vix/vix_deps.cmake

This file can:

add package roots to CMAKE_PREFIX_PATH
add header-only packages as interface targets
add CMake-based dependencies with add_subdirectory
disable dependency tests, examples, benchmarks, and docs
bridge package targets to canonical Vix aliases
expose aliases such as gk::json

The canonical alias for a registry package is:

txt

namespace::name

For:

txt

gk/json

the alias is:

txt

gk::json

Header-only packages

Header-only packages expose include directories through an interface target.

Example package:

txt

gk/json

Expected alias:

txt

gk::json

After vix install, use it from CMake through:

cmake

target_link_libraries(app PRIVATE gk::json)

For vix.app, add the alias to links:

ini

links = [
  vix::vix,
  gk::json,
]

1
2
3
4

Compiled packages

Compiled packages can contain their own CMakeLists.txt.

When Vix detects a CMake-based package, it can load the package through generated CMake integration.

Vix also tries to bridge the package’s real CMake target to the canonical registry alias.

For example:

txt

gk/http

should be usable as:

txt

gk::http

when the dependency exposes a compatible target.

Dependency order

When dependencies depend on other dependencies, Vix sorts them topologically before generating CMake integration.

This matters because a dependency should be available before another package tries to use it.

If Vix detects a dependency cycle, it reports an error.

Example shape:

txt

dependency cycle detected while generating .vix/vix_deps.cmake

vix.app projects

For vix.app projects, vix install is simple.

After install, Vix prints a next step like:

txt

Dependencies ready
1 package(s) installed
CMake integration generated

Next:
  run vix build

1
2
3
4
5
6

That is because vix.app generated CMake can load the generated dependency integration automatically.

A typical vix.app dependency flow:

bash

vix add gk/json@^1.0.0
vix install
vix build

1
2
3

Then in vix.app:

ini

deps = [
  gk/json@^1.0.0,
]

links = [
  vix::vix,
  gk::json,
]

1
2
3
4
5
6
7
8

CMake projects

For manual CMake projects, Vix may print a next step like:

cmake

include(.vix/vix_deps.cmake)
add_executable(app main.cpp)
target_link_libraries(app PRIVATE gk::json)

1
2
3

In a real project, add:

cmake

include(.vix/vix_deps.cmake)

near the top of your CMakeLists.txt after project(...).

Then link only the packages your target actually uses:

cmake

target_link_libraries(app PRIVATE gk::json)

vix.app vs CMake install behavior

Project type	What you do after `vix install`
`vix.app` project	Run `vix build`.
CMake project	Include `.vix/vix_deps.cmake` and link needed aliases.

Vix detects a vix.app project when:

txt

vix.app exists
CMakeLists.txt does not exist

1
2

If CMakeLists.txt exists, Vix treats the project as a CMake project.

Full `vix.app` example

ini

name = api
type = executable
standard = c++20

sources = [
  src/main.cpp,
]

include_dirs = [
  src,
]

deps = [
  gk/json@^1.0.0,
]

packages = [
  vix,
]

links = [
  vix::vix,
  gk::json,
]

output_dir = bin

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

Install:

bash

vix install

Build:

bash

vix build

Run:

bash

vix run

Full CMake example

cmake

cmake_minimum_required(VERSION 3.24)

project(api LANGUAGES CXX)

include(.vix/vix_deps.cmake)

add_executable(api
  src/main.cpp
)

target_compile_features(api PRIVATE cxx_std_20)

target_link_libraries(api PRIVATE
  gk::json
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Install:

bash

vix install
vix build

1
2

Global install example

Install:

bash

vix registry sync
vix install -g gk/jwt@^1.0.0

1
2

This writes global install state under:

txt

~/.vix/global/

Typical structure:

txt

~/.vix/global/
├── packages/
│   └── ...
└── installed.json

1
2
3
4

The global manifest records information such as:

json

{
  "packages": [
    {
      "id": "gk/jwt",
      "version": "1.0.0",
      "repo": "https://github.com/...",
      "tag": "v1.0.0",
      "commit": "...",
      "hash": "...",
      "type": "header-only",
      "include": "include",
      "installed_path": "/home/user/.vix/global/packages/gk.jwt"
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Package specification

A package spec has this shape:

txt

namespace/name

Optional version or range:

txt

namespace/name@version
namespace/name@range

1
2

Examples:

txt

gk/json
gk/json@1.0.0
gk/json@^1.0.0
gk/json@~1.2.0

1
2
3
4

Scoped-style syntax is also accepted:

txt

@gk/json
@gk/json@1.0.0

1
2

Invalid package spec

Wrong:

bash

vix install -g jwt

Correct:

bash

vix install -g gk/jwt

If the package spec is invalid or not found, Vix reports:

txt

invalid package spec or package not found: jwt
Expected: @namespace/name[@version]
Example: vix install -g @gk/jwt@1.0.0

1
2
3

Project mode requires `vix.lock`

Project mode installs from:

txt

vix.lock

If the lockfile is missing, create it by adding or updating dependencies.

Typical flow:

bash

vix registry sync
vix add gk/json@^1.0.0
vix install

1
2
3

or:

bash

vix update
vix install

1
2

Manual edits to `vix.json`

Avoid manually editing dependency ranges in vix.json without updating the lockfile.

If you change dependency ranges manually, run:

bash

vix update
vix install

1
2

or use:

bash

vix add <package>

so vix.json and vix.lock stay aligned.

CI usage

Project install is the right command for CI because it respects vix.lock.

Example:

bash

vix registry sync
vix install
vix build --build-target all
vix tests

1
2
3
4

Release build:

bash

vix registry sync
vix install
vix build --preset release --build-target all
vix tests --preset release

1
2
3
4

With validation:

bash

vix registry sync
vix install
vix check --tests

1
2
3

Options

Option	Description
`-g, --global`	Install one package globally.
`-h, --help`	Show command help.

Commands reference

Command	Purpose
`vix install`	Install project dependencies from `vix.lock`.
`vix install -g <pkg>`	Install one package globally.
`vix install --global <pkg>`	Same as `-g`.

Common workflows

Install project dependencies

bash

vix install

Install after clone

bash

git clone https://github.com/example/api.git
cd api
vix registry sync
vix install
vix build

1
2
3
4
5

Install then run dev mode

bash

vix install
vix dev

1
2

Add and install a dependency

bash

vix registry sync
vix add gk/json@^1.0.0
vix install
vix build

1
2
3
4

Install a global package

bash

vix registry sync
vix install -g gk/jwt

1
2

Install a specific global version

bash

vix install -g gk/jwt@1.0.0

Install a global semver range

bash

vix install -g gk/jwt@^1.0.0

Common mistakes

Expecting `vix install` to update dependencies

Wrong expectation:

txt

vix install should choose newer versions

Correct model:

txt

vix install installs locked versions

Use:

bash

vix outdated
vix update

1
2

when you want to inspect and update versions.

Editing `vix.json` and expecting install to resolve new ranges

If you manually edit dependencies in vix.json, update the lockfile first:

bash

vix update
vix install

1
2

Better:

bash

vix add gk/json@^1.0.0
vix install

1
2

Forgetting registry sync

If the package cannot be found, run:

bash

vix registry sync
vix install

1
2

For global packages:

bash

vix registry sync
vix install -g gk/jwt

1
2

Using global install when the project needs a dependency

Wrong:

bash

vix install -g gk/json
vix build

1
2

Correct:

bash

vix add gk/json@^1.0.0
vix install
vix build

1
2
3

Global install does not add the dependency to your project lockfile.

Forgetting to link the package

Installing a dependency does not automatically mean your target uses it.

For vix.app, add the alias to links:

ini

links = [
  vix::vix,
  gk::json,
]

1
2
3
4

For CMake:

cmake

target_link_libraries(api PRIVATE gk::json)

Editing `.vix/vix_deps.cmake`

Wrong:

txt

edit .vix/vix_deps.cmake manually

Correct:

txt

edit vix.json, vix.lock, vix.app, or CMakeLists.txt

The file is generated and can be replaced by the next install.

Confusing `deps` and `links` in vix.app

Wrong:

ini

deps = [
  gk::json,
]

1
2
3

Correct:

ini

deps = [
  gk/json@^1.0.0,
]

links = [
  gk::json,
]

1
2
3
4
5
6
7

deps uses registry package specs.

links uses CMake target aliases.

Troubleshooting

Registry not synced

Run:

bash

vix registry sync

Then try again:

bash

vix install

Package not found

Check the package name:

txt

namespace/name

Then sync the registry:

bash

vix registry sync

Try:

bash

vix install -g namespace/name

or add it to your project:

bash

vix add namespace/name

No version matches range

If Vix reports:

txt

no version matches range: gk/json@^2.0.0

the registry has no compatible version.

Use:

bash

vix outdated

or check available versions in the registry.

Dependency hash mismatch

If integrity verification fails, do not ignore it.

Run:

bash

vix registry sync
vix reset
vix install

1
2
3

If it still fails, the registry entry or package content may be inconsistent.

Dependency cycle detected

If Vix reports a dependency cycle, one or more packages depend on each other in a loop.

Fix the package dependency metadata.

CMake cannot find dependency target

Check that install generated:

txt

.vix/vix_deps.cmake

For CMake projects, make sure you included it:

cmake

include(.vix/vix_deps.cmake)

For vix.app, make sure the dependency alias is in links:

ini

links = [
  gk::json,
]

1
2
3

Header not found

Check that the dependency exposes the expected include directory.

Then make sure your target links the dependency alias.

Example:

cmake

target_link_libraries(api PRIVATE gk::json)

or in vix.app:

ini

links = [
  gk::json,
]

1
2
3

Compiled package has no CMakeLists.txt

If a package is marked as compiled but has no CMakeLists.txt, Vix cannot build it as a CMake dependency.

Fix the package metadata or add a valid package build file.

Best practices

Commit vix.json.

Commit vix.lock.

Do not commit .vix/deps.

Do not manually edit .vix/vix_deps.cmake.

Run vix registry sync before adding or resolving dependencies.

Use vix add to add dependencies.

Use vix install after clone or in CI.

Use vix update only when you intentionally want new dependency versions.

Use deps for registry specs in vix.app.

Use links for CMake aliases in vix.app.

Prefer canonical aliases:

txt

namespace::name

Keep project installs reproducible with vix.lock.

Command	Purpose
`vix add`	Add a new dependency to the project.
`vix update`	Resolve newer versions and rewrite `vix.lock`.
`vix outdated`	Check outdated dependencies.
`vix remove`	Remove a dependency.
`vix list`	List installed project dependencies.
`vix reset`	Clean and reinstall project dependency state.
`vix registry sync`	Refresh the registry index.
`vix build`	Build the project after install.
`vix run`	Run the app after install.
`vix dev`	Start dev mode after install.

Next step

Update dependency versions intentionally.

Open the vix update guide

vix install ​

Overview ​

Usage ​

Basic examples ​

What it does ​

Project mode ​

Project install outputs ​

Global mode ​

Global install syntax ​

Version resolution ​

Registry requirement ​

Project install workflow ​

Registry dependency workflow ​

Difference between vix add and vix install ​

Difference between vix update and vix install ​

Difference between project and global install ​

Package cache ​

Integrity checks ​

Generated CMake integration ​

Header-only packages ​

Compiled packages ​

Dependency order ​

vix.app projects ​

CMake projects ​

vix.app vs CMake install behavior ​

Full vix.app example ​

Full CMake example ​

Global install example ​

Package specification ​

Invalid package spec ​

Project mode requires vix.lock ​

Manual edits to vix.json ​

CI usage ​

Options ​

Commands reference ​

Common workflows ​

Install project dependencies ​

Install after clone ​

Install then run dev mode ​

Add and install a dependency ​

Install a global package ​

Install a specific global version ​

Install a global semver range ​

Common mistakes ​

Expecting vix install to update dependencies ​

Editing vix.json and expecting install to resolve new ranges ​

Forgetting registry sync ​

Using global install when the project needs a dependency ​

Forgetting to link the package ​

Editing .vix/vix_deps.cmake ​

Confusing deps and links in vix.app ​

Troubleshooting ​

Registry not synced ​

Package not found ​

No version matches range ​

Dependency hash mismatch ​

Dependency cycle detected ​

CMake cannot find dependency target ​

Header not found ​

Compiled package has no CMakeLists.txt ​

Best practices ​

Related commands ​

Next step ​

vix install

Overview

Usage

Basic examples

What it does

Project mode

Project install outputs

Global mode

Global install syntax

Version resolution

Registry requirement

Project install workflow

Registry dependency workflow

Difference between `vix add` and `vix install`

Difference between `vix update` and `vix install`

Difference between project and global install

Package cache

Integrity checks

Generated CMake integration

Header-only packages

Compiled packages

Dependency order

vix.app projects

CMake projects

vix.app vs CMake install behavior

Full `vix.app` example

Full CMake example

Global install example

Package specification

Invalid package spec

Project mode requires `vix.lock`

Manual edits to `vix.json`

CI usage

Options

Commands reference

Common workflows

Install project dependencies

Install after clone

Install then run dev mode

Add and install a dependency

Install a global package

Install a specific global version

Install a global semver range

Common mistakes

Expecting `vix install` to update dependencies

Editing `vix.json` and expecting install to resolve new ranges

Forgetting registry sync

Using global install when the project needs a dependency

Forgetting to link the package

Editing `.vix/vix_deps.cmake`

Confusing `deps` and `links` in vix.app

Troubleshooting

Registry not synced

Package not found

No version matches range

Dependency hash mismatch

Dependency cycle detected

CMake cannot find dependency target

Header not found

Compiled package has no CMakeLists.txt

Best practices

Related commands

Next step