vix remove removes a package dependency from the current project lockfile.

Use it when your project no longer needs a locked package dependency.

vix remove gk/jwt

vix remove removes one dependency from:

vix.lock

It can also delete the project-local dependency folder under:

.vix/deps/

when --purge is used.

It does not remove a package from the Vix Registry.

It does not uninstall a global package.

It does not currently rewrite vix.json.

vix remove [@]namespace/name[@version]
vix remove [@]namespace/name[@version] --purge [-y]

# Remove a locked dependency
vix remove gk/jwt

# Scoped-style syntax
vix remove @gk/jwt

# Remove only if the locked version matches
vix remove gk/jwt@1.0.0

# Scoped-style syntax with version
vix remove @gk/jwt@1.0.0

# Remove and delete project-local dependency files
vix remove @gk/jwt --purge

# Remove and purge without confirmation
vix remove @gk/jwt --purge -y

When you run:

vix remove gk/jwt

Vix does this:

1. Parses the package target.
2. Reads vix.lock.
3. Finds the matching dependency in the lockfile.
4. Removes the first matching dependency entry.
5. Writes the updated vix.lock.
6. Optionally deletes .vix/deps/<namespace>.<name> when --purge is used.
7. Prints a tip to regenerate dependency integration if needed.

vix remove currently removes from:

vix.lock

It does not remove the dependency declaration from:

vix.json

So after removing a dependency, check whether vix.json still contains it.

If it is still declared there, remove it manually or use the dependency workflow that matches your project.

A package target uses this format:

namespace/name

Examples:

gk/jwt
gk/json

Scoped-style syntax is also accepted:

@namespace/name

Example:

@gk/jwt

Both forms refer to the same dependency id:

gk/jwt

You can pass a version:

vix remove gk/jwt@1.0.0

When a version is provided, Vix removes the dependency only if the locked dependency matches that version.

Vix checks:

version
tag

If the lockfile uses a tag like:

v1.0.0

then this still matches:

vix remove gk/jwt@1.0.0

vix remove requires:

vix.lock

If the lockfile is missing, Vix reports:

missing lock file: /path/to/project/vix.lock
Run: vix add <pkg>@<version> first

This command is lockfile-based.

vix remove expects a lockfile with:

{
  "dependencies": [
    {
      "id": "gk/jwt",
      "version": "1.0.0"
    }
  ]
}

If the lockfile does not contain a dependencies array, Vix reports:

invalid lock: missing 'dependencies' array
Tip: regenerate lock by re-adding dependencies

Run:

vix remove gk/jwt

Example output shape:

Remove
id: gk/jwt
✔ removed from vix.lock: gk/jwt
✔ lock:  /home/user/api/vix.lock
⚠ Tip: run 'vix install' to regenerate .vix/vix_deps.cmake if needed.

Run:

vix remove gk/jwt@1.0.0

Example output shape:

Remove
id: gk/jwt
version: 1.0.0
✔ removed from vix.lock: gk/jwt
✔ lock:  /home/user/api/vix.lock
⚠ Tip: run 'vix install' to regenerate .vix/vix_deps.cmake if needed.

If the dependency exists but the version does not match, Vix reports:

dependency not found in lock: gk/jwt
Tip: use 'vix list' to check current deps

Use --purge to delete the project-local dependency folder.

vix remove gk/jwt --purge

For package:

gk/jwt

Vix deletes:

.vix/deps/gk.jwt

The folder format is:

.vix/deps/<namespace>.<name>

Examples:

When --purge is used, Vix asks for confirmation before deleting files.

Example:

This will also delete files from this project:
/home/user/api/.vix/deps/gk.jwt
Type DELETE to confirm:

You must type:

DELETE

If you type anything else, Vix cancels:

cancelled

Use -y or --yes:

vix remove gk/jwt --purge -y

or:

vix remove gk/jwt --purge --yes

This skips confirmation and deletes the project-local dependency folder if it exists.

--purge deletes the project-local dependency folder under:

.vix/deps/

It does not delete the global Git store.

It does not delete registry metadata.

It does not delete a globally installed package.

For global packages, use the global uninstall workflow.

vix remove can affect:

vix.lock
.vix/deps/<namespace>.<name>   # only with --purge

It may require regenerating:

.vix/vix_deps.cmake

That is why Vix prints:

vix install

after removal.

After removing a dependency, validate the project.

vix install
vix build
vix check --tests

If your source code still includes headers from the removed package, the build will fail.

Remove those includes and target links.

For vix.app projects, check these places after removal:

vix.lock
vix.json
vix.app

If the package is still declared in vix.app, remove it from:

deps = [
  gk/jwt@^1.0.0,
]

links = [
  gk::jwt,
]

Example cleanup:

deps = [
]

links = [
  vix::vix,
]

Then run:

vix install
vix build

For CMake projects, remove the dependency link if the target is no longer used.

Example before:

target_link_libraries(api PRIVATE
  gk::jwt
)

After:

target_link_libraries(api PRIVATE
)

Then regenerate dependency integration if needed:

vix install
vix build

Use vix remove for project dependencies.

Use vix uninstall -g for global packages.

Prefer vix remove.

Remove the dependency:

vix remove gk/jwt

Regenerate dependency integration:

vix install

Remove usage from source code, vix.app, or CMake.

Validate:

vix build
vix check --tests

vix remove gk/jwt --purge -y
vix install
vix build
vix check --tests

Use --purge when you want to clean project-local dependency files too.

vix remove gk/jwt
vix install
vix build

vix remove @gk/jwt
vix install
vix build

vix remove gk/jwt@1.0.0
vix install
vix build

vix remove @gk/jwt --purge -y
vix install
vix build

vix remove gk/jwt
vix install
vix check --tests

vix remove only affects the current project.

It does not remove anything from the registry.

Wrong:

vix remove gk/jwt

when you mean a global install.

Use the global uninstall command instead:

vix uninstall -g gk/jwt

The current command removes from vix.lock.

Check vix.json after removal.

If the dependency is still declared there, remove or update it intentionally.

For vix.app projects, also remove unused entries from:

deps
links

For CMake projects, remove unused target links such as:

target_link_libraries(api PRIVATE gk::jwt)

After removing a dependency, remove includes such as:

#include <jwt/api.hpp>

Then run:

vix check --tests

After changing dependency state, run:

vix install

This regenerates:

.vix/vix_deps.cmake

Wrong:

vix remove jwt

Correct:

vix remove gk/jwt

If you run:

vix remove

Vix reports a missing package id and shows help.

Use:

vix remove namespace/name

Example:

vix remove gk/jwt

Use a valid package id:

namespace/name

Valid:

vix remove gk/jwt
vix remove @gk/jwt

Invalid:

vix remove jwt
vix remove @/jwt
vix remove gk/

If Vix reports:

missing lock file

the project has no vix.lock.

Check the current directory.

If this is a Vix project with dependencies, recreate dependency state:

vix add <pkg>

or restore vix.lock from version control.

If Vix reports:

invalid lock: missing 'dependencies' array

regenerate the lockfile by re-adding dependencies or restoring a valid lockfile.

If Vix reports:

dependency not found in lock: gk/jwt

check current dependencies:

vix list

The package may already be removed, or the id may be different.

When using --purge, type exactly:

DELETE

or pass:

-y

if you intentionally want to skip confirmation.

If Vix reports:

failed to delete: .vix/deps/gk.jwt

check permissions:

ls -ld .vix/deps/gk.jwt

Then fix ownership or remove manually if needed.

Use vix list before removing dependencies.

Remove the dependency from source code before or after running vix remove.

For vix.app, remove unused package specs from deps.

For vix.app, remove unused CMake aliases from links.

For CMake, remove unused target_link_libraries entries.

Run vix install after removing dependencies.

Run vix build after removal.

Run vix check --tests before committing.

Use --purge when you want to clean .vix/deps.

Do not manually edit vix.lock.

Do not confuse project dependencies with global packages.

List project dependencies.

Open the vix list guide