VNMA (Vendor Manager)

Status: Beta (v0.3.0)
Platform Support: CPython 3.11, 3.12, 3.13, 3.14 (Tested on Windows and Linux)

vnma is a dependency and vendoring manager for Python projects. It installs and manages dependencies inside a local project directory (vendor/ or vendor_vnma/) instead of creating full Python virtual environments (venv).

What VNMA Does (and What It Doesn't)

What it does:

• Installs packages locally: Downloads, verifies, and unpacks wheels directly into vendor/.
• Runtime path isolation: Cleans sys.path so your application loads third-party libraries strictly from vendor/, ignoring global or user site-packages.
• Automatic DLL registration (Windows): Automatically calls os.add_dll_directory() for folders containing native binaries (e.g., SDL2, C extensions), preventing import errors.
• Transactional operations: Installations and updates are staged in a private directory and committed atomically; if an install fails or crashes, previous state is restored via a recovery journal.
• Transitive dependency resolution: Resolves dependencies and version constraints with bounded backtracking and PEP 508 marker evaluation.
• Live development links (vnma link): Connects local libraries in development without copying files, keeping dependencies synchronized.
• IDE configuration: Configures extraPaths in VS Code (.vscode/settings.json) and PYTHONPATH in PyCharm (.env, .idea/*.iml).

What it doesn't do:

• It does not virtualize the Python executable: It uses your installed Python interpreter and standard library directly.
• It cannot load multiple incompatible versions of the same library simultaneously: Python's runtime has a single global sys.modules. Conflicting version requirements are rejected at resolution time.

Step-by-Step Guide

Step 1: Install VNMA

Install vnma using pip:

pip install vnma

Or install in editable mode from source:

git clone https://github.com/GrandKenzy/vnma.git
cd vnma
pip install -e .

Verify the installation:

vnma --help

Step 2: Initialize Your Project

Navigate to your project folder and run:

cd my_project
vnma init

This command creates:

1. vnma.toml: Declarative manifest for your project and dependencies.
2. vendor/: Directory for vendored packages.
3. vendor/__bootstrap__.py & vendor/__init__.py: Runtime loader and path sanitizer.
4. .gitignore entries: Ignores vendored packages in Git.
5. IDE settings: Preconfigures VS Code (.vscode/settings.json) and PyCharm (.env).
6. vnma.lock: Lockfile for reproducible installs.

Step 3: Install Packages

From PyPI:

# Latest compatible version:
vnma install requests

# Pinned version:
vnma install colorama==0.4.6

# Multiple packages:
vnma install flask pytest

From a local directory:

vnma install ../shared-library

From a Git repository:

vnma install git+https://github.com/psf/requests.git@main

Step 4: Run Your Code

You have two ways to execute your code with vendored packages:

Option A: Using the CLI (Recommended)

vnma run main.py

vnma run sets PYTHONPATH to your vendor directory and disables user-site packages automatically.

Option B: Direct Python execution

Add this import at the very top of your entry script (main.py):

import vendor.__bootstrap__
import requests

response = requests.get("https://httpbin.org/get")
print(response.status_code)

Then run normally with your system Python:

python main.py

Step 5: Link Local Libraries for Development (vnma link)

When actively developing an internal library alongside an app, avoid re-installing wheels after every change:

vnma link ../my-library

• Zero-copy: Does not copy files; imports live directly from the library's source directory.
• Auto-dependency resolution: Reads the library's dependencies and installs them into vendor/.
• To unlink:

  vnma unlink my-library
  

• To check and synchronize linked libraries:

  vnma reload
  

Step 6: Maintain and Clean Your Project

List installed packages:

vnma list

Update dependencies:

# Update all unpinned dependencies:
vnma update

# Update only PyPI packages:
vnma update --pip

# Update only Git repositories:
vnma update --git

Remove orphaned packages (packages no longer required):

# Preview what would be removed:
vnma prune --dry-run

# Remove unused packages:
vnma prune --yes

Uninstall a package:

# Remove from vendor directory:
vnma uninstall requests

# Remove from vendor directory AND delete from vnma.toml:
vnma uninstall requests -d

Restore dependencies on another machine or in CI:

vnma install

Configuration Reference

vnma.toml (Project Level)

[project]
name = "my-app"
version = "1.0.0"

[dependencies]
requests = ">=2.31.0"
colorama = "==0.4.6"
local-tool = { path = "../local-tool" }

[tool.vnma]
vendor_dir = "vendor"
ide_integration = ["vscode", "pycharm"]

vnma_config.toml (Optional Library Manifest)

If developing a library with native DLLs or specific exports, place a vnma_config.toml in its root:

[package]
name = "my-library"
package = "my_library"  # Python import name (import my_library)
version = "0.1.0"

[runtime]
dll_directories = ["my_library/libs"]
hermetic = true

[exports]
modules = ["my_library"]
entry_points = { my-tool = "my_library.cli:main" }

Command Summary

Documentation

Full documentation is available in the docs/ directory:

• Getting Started: docs/en/01-Use/01-getting-started.md
• Dependency Management: docs/en/01-Use/02-dependency-management.md
• Configuration Specifications: docs/en/01-Use/03-configuration-specs.md
• Runtime Execution Model: docs/en/01-Use/04-runtime-execution.md
• IDE Integration: docs/en/01-Use/05-ide-integration.md
• Beta Status & Limitations: docs/en/02-Advice/01-beta-status.md
• Changelog: CHANGELOG.md

License

This software is released under a modified permissive license. See LICENSE for terms.