Skip to content
VowVow Docs

vpm (package manager)

vpm is Vow’s package manager — install, publish, and search packages. End users get it with vow via the curl installer (no separate pip install).

Terminal window
curl -fsSL https://install.vowlang.dev | sh
export PATH="$HOME/.local/bin:$PATH"
vpm init my-api
vpm add vow-web-server@0.2.2
vpm install

Commands

Section titled “Commands”
Terminal window
vpm init [dir]                         # scaffold project.toml + src/main.vow
vpm install                            # resolve deps → .vow/deps/
vpm add pkg@0.1.0                      # registry dependency
vpm add my-lib --git https://github.com/org/my-lib
vpm add my-lib --path ../my-lib
vpm add vow-serve -g                       # global CLI (vow-serve, vs, vds)
vpm add vow-serve --path ../vow-serve -g   # monorepo / offline
vpm publish                            # PUT tarball (needs token)
vpm search web-server
vpm config set registry <url>
vpm login                              # save publish token

Default registry: https://vpm.vowlang.dev (override with vpm config set registry or VPM_REGISTRY).

Async I/O in HTTP apps

Section titled “Async I/O in HTTP apps”

Pair vow-web-server with vow-postgres (or file async) using language async fn / await / block_on:

Terminal window
vpm add vow-web-server vow-postgres
vpm install
async fn list_rows() -> String {
    return await db_query(g_handle, "SELECT id, title FROM todos")?;
}


fn list_todos(_req: request.Request) -> response.Response {
    return vws.json("{\"todos\":" + block_on(list_rows) + "}");
}

Guide: Async / await · full demo: hello-app/

Global install (-g)

Section titled “Global install (-g)”

Project libraries use vpm add (.vow/deps/). CLI tools use vpm add -g — similar to npm install -g pm2.

Terminal window
vpm add vow-serve -g
export PATH="$HOME/.vow/global/bin:$PATH"
vow-serve --version
vds --help

Ergonomic alias: vow add vow-serve -g (delegates to vpm).

Path Purpose
~/.vow/global/deps/<pkg>/ Global package tree
~/.vow/global/bin/ Symlinked commands
~/.vow/global/lock.toml Global lock file

vow-serve workflow

Section titled “vow-serve workflow”

After global install, deploy vow-web-server apps with vow-serve and vds:

Terminal window
cd my-api
vow-serve init              # vow.serve.toml, vow.grants.toml, templates
vds                         # dev — watch + rebuild
vow-serve start             # prod — registry in ~/.vow/serve/
vow-serve list
vow-serve logs my-api -f
vow-serve stop my-api

See Deploying vow-web-server and vow-serve.

Monorepo / offline

Section titled “Monorepo / offline”
Terminal window
vpm add vow-serve --path ../vow-frameworks/vow-serve -g
export VPM_LOCAL_STORE=/path/to/registry/store   # optional tarball mirror

Troubleshooting

Section titled “Troubleshooting”
Problem Fix
vow-serve: command not found vpm add vow-serve -g; add ~/.vow/global/bin to PATH
Registry unreachable --path or VPM_LOCAL_STORE
Stale global install Remove ~/.vow/global/deps/<pkg> and reinstall

Import styles

Section titled “Import styles”
Syntax Meaning
import vow_web_server.router Submodule; alias = last segment (router)
import r from vow_web_server.router Submodule with custom alias
import vws from vow_web_server Package entry (main in the dep’s project.toml)

Package names normalize - ↔ _ (vow-web-server ↔ vow_web_server).

project.toml

Section titled “project.toml”
name = "my-api"
version = "0.1.0"


[deps]
vow-web-server = "0.2.2"
my-lib = { git = "git+https://github.com/org/my-lib" }
local = { path = "../my-lib" }

Published libraries declare an entry point:

name = "vow-web-server"
version = "0.2.0"
main = "lib/index.vow"

CLI packages declare [bin]:

name = "vow-serve"
version = "0.1.0"


[bin]
vow-serve = "bin/vow-serve"
vs = "bin/vow-serve"
vds = "bin/vds"

Install globally with vpm add vow-serve -g. Paths in [bin] are relative to the package root.

Vow CLI integration

Section titled “Vow CLI integration”
  • vow build / vow run / vow check auto-run vpm install when lock/deps are missing (if vpm is on PATH)
  • vow add pkg -g delegates to vpm add pkg -g
  • vow serve … delegates to vow-serve on PATH
  • Prefer vpm add / vpm install over deprecated vow add / vow sync for project deps

Publishing

Section titled “Publishing”
Terminal window
vpm login
vpm publish

Packs the project and publishes to the configured registry (cloud or local). Sign up on the registry UI for a publish token, then vpm login.

CLI packages: include executable bin/* files and document vpm add <pkg> -g in the README.

Production registry (cloud)

Section titled “Production registry (cloud)”

The hosted registry runs on Vercel + Firebase (vow-package-manager/registry-cloud/):

  • UI + API on Vercel
  • Auth / Firestore metadata / Storage tarballs on Firebase
  • Default client URL: https://vpm.vowlang.dev

Contributors: see registry-cloud/README.md for Firebase + Vercel env setup and npm run seed.

Local registry (contributors)

Section titled “Local registry (contributors)”

From the vow-package-manager tree:

Terminal window
cd registry
./seed.sh                 # bootstrap vow-web-server@0.2.2 into data/
vpm install
vpm serve --watch         # UI + API at http://127.0.0.1:8787/

Then point another project at it:

Terminal window
vpm config set registry http://127.0.0.1:8787
vpm add vow-web-server@0.2.2
vpm install

See examples/http-api/ in that repo.

Section titled “Featured package: vow-web-server”

HTTP API framework with a three-tier grant model: grants.toml (supply), use_grant_at (middleware demand), get_needs / post_needs (API demand).

  • Full docs: vow-web-server
  • vpm markdown (clone): vow-package-manager/docs/vow-web-server.md

Next

Section titled “Next”