Package management

A V module is a single folder with .v files inside. A V package can contain one or more V modules. A V package should have a v.mod file at its top folder, describing the contents of the package.

That v.mod file is also the package's relative module anchor. When V compiles a file beside or below it, imports are resolved relative to the folder containing v.mod.

V packages are installed normally in your ~/.vmodules folder. That location can be overridden by setting the env variable VMODULES.

v install --local installs into the project's own lookup root instead, i.e. the folder holding its v.mod, so the package lands beside the project's own modules and is imported by its name just like they are. That root is shared with the modules the project writes itself, so VPM keeps a record of what it installed there and only updates or removes those. A package an older V installed into the project's modules/ directory has no such record; after moving it up beside the v.mod, v install --local --adopt <module> tells VPM it is one of its own.

Package names and import paths

A package name can contain characters that are not valid in a V import path, for example - or uppercase letters. Such names are normalized when the package is installed: - becomes _ and the name is lowercased. A package named my-mod is therefore installed as ~/.vmodules/my_mod and imported with import my_mod. The same applies to the publisher part of a VPM package name, so Some-Publisher.repo is installed as ~/.vmodules/some_publisher/repo and imported with import some_publisher.repo.

v install prints a warning with the resulting import prefix whenever it has to normalize a name. A package may contain only nested modules, so append the nested module path when needed (for example, import my_mod.json). If you publish a package, prefer a name in v.mod that is already a valid import path.

Package commands

You can use the V frontend to do package operations, just like you can use it for compiling code, formatting code, vetting code etc.

v [package_command] [param]

where a package command can be one of:

   install           Install a package from VPM.
   remove            Remove a package that was installed from VPM.
   search            Search for a package from VPM.
   update            Update an installed package from VPM.
   upgrade           Upgrade all the outdated packages.
   list              List all installed packages.
   outdated          Show installed packages that need updates.

You can install packages already created by someone else with VPM:

v install [package]

Example:

v install ui

Packages can be installed directly from git or mercurial repositories.

v install [--once] [--git|--hg] [url]

Example:

v install --git https://github.com/vlang/markdown

Sometimes you may want to install the dependencies ONLY if those are not installed:

v install --once [package]

Removing a package with v:

v remove [package]

Example:

v remove ui

Updating an installed package from VPM:

v update [package]

Example:

v update ui

Or you can update all your packages:

v update

To see all the packages you have installed, you can use:

v list

Example:

> v list
Installed packages:
  markdown
  ui

To see all the packages that need updates:

v outdated

Example:

> v outdated
Package are up to date.

Publish package

  1. Put a v.mod file inside the toplevel folder of your package (if you created your package with the command v new mypackage or v init you already have a v.mod file).

    v new mypackage
Input your project description: My nice package.
Input your project version: (0.0.0) 0.0.1
Input your project license: (MIT)
Initialising ...
Complete!

    The prompts above appear only when running in a terminal; with a non-terminal stdin the defaults are used instead (see Getting started).

    Example v.mod:

    Module { name: 'mypackage' base_url: 'src' description: 'My nice package.' version: '0.0.1' license: 'MIT' dependencies: [] }

    base_url is optional. When set, V resolves the package sources relative to that folder, next to the v.mod file.

    Minimal file structure:

    v.mod
mypackage.v

    You can also add subdirs: ['internal'] to v.mod to compile files from selected subdirectories as part of the same module. These paths are relative to the module source root, and files there should declare the same module mypackage.

    The name of your package should be used with the module directive at the top of all files in your package. For mypackage.v:

    module mypackage pub fn hello_world() { println('Hello World!') }

  2. Create a git repository in the folder with the v.mod file (this is not required if you used v new or v init):

    git init
git add .
git commit -m "INIT"

  3. Create a public repository on github.com.

  4. Connect your local repository to the remote repository and push the changes.

  5. Add your package to the public V package registry VPM: https://vpm.vlang.io/new

    You will have to login with your Github account to register the package. Warning: Currently it is not possible to edit your entry after submitting. Check your package name and github url twice as this cannot be changed by you later.

  6. The final package name is a combination of your github account and the package name you provided e.g. mygithubname.mypackage.

Optional: tag your V package with vlang and vlang-package on github.com to allow for a better search experience.

Advanced Topics

On this page