Skip to content

Getting Started

Pyve is a command-line tool that gives every project a single, declarative entry point for setting up and managing its environments on macOS and Linux — across language ecosystems. It orchestrates version managers (asdf/pyenv for Python; nvm/fnm/volta for Node), environment backends (venv/micromamba; pnpm/npm/yarn), and direnv for automatic activation, all driven from a root-level pyve.toml manifest.

This guide gets a single-stack Python project running. For named environments, the manifest, plugins, and multi-stack repos, see Named Environments, pyve.toml Reference, Plugins, and Polyglot Projects.

Installation

The easiest way to install Pyve is via Homebrew:

brew install pointmatic/tap/pyve

To update Pyve:

brew upgrade pointmatic/tap/pyve

To uninstall:

brew uninstall pyve

Git Clone (Manual Installation)

If you prefer to install from source:

# Clone the repository
git clone https://github.com/pointmatic/pyve.git
cd pyve

# Install to ~/.local/bin
./pyve.sh self install

# Verify installation
pyve --version

To update a manual installation:

cd /path/to/pyve
git pull origin main
./pyve.sh self install

To uninstall:

pyve self uninstall

Prerequisites

For a Python project, Pyve requires one of the following version managers:

  • asdf with the python plugin
  • pyenv

For a Node project, Pyve resolves the runtime through any of nvm, fnm, volta, asdf, or a Homebrew/system Node.

Optional, across stacks:

  • direnv (for automatic environment activation)
  • micromamba (for conda-based Python environments — Pyve can bootstrap it for you)

Installing Prerequisites

# Install asdf (recommended)
brew install asdf
asdf plugin add python

# Or install pyenv
brew install pyenv

# Optional: Install direnv for auto-activation
brew install direnv

# Optional: Install micromamba for conda environments
brew install micromamba

# Install asdf (recommended)
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.0
echo '. "$HOME/.asdf/asdf.sh"' >> ~/.bashrc
asdf plugin add python

# Or install pyenv
curl https://pyenv.run | bash

# Optional: Install direnv
# See https://direnv.net/docs/installation.html

# Optional: Install micromamba
# See https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html

Quick Start

1. Initialize a New Project

Navigate to your project directory and initialize Pyve:

cd my-project
pyve init

This will:

  • Detect or prompt for Python version
  • Auto-detect backend (venv or micromamba) from project files
  • Prompt for backend choice if both environment.yml and pyproject.toml exist
  • Create a virtual environment (.venv by default for venv, .pyve/envs/<name> for micromamba)
  • Upgrade pip to the latest version
  • Prompt to install pip dependencies from pyproject.toml or requirements.txt
  • Generate .envrc for direnv (if installed)
  • Add entries to .gitignore

Note: Pyve uses interactive prompts to help you choose the right backend and install dependencies. For automated workflows, use --backend, --auto-install-deps, or --no-install-deps flags. See the Backends Guide for details.

2. Activate the Environment

If you have direnv installed, the environment activates automatically when you cd into the directory.

Without direnv, activate manually:

source .venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Verify Setup

Snapshot what the project is:

pyve status      # read-only dashboard (always exits 0)

Or diagnose problems with CI-safe exit codes:

pyve check       # 0 = healthy, 2 = warnings, 1 = errors

pyve status displays the project's backend, environments, Python version, and integrations; pyve check surfaces problems and suggests one remediation per failure.

Coming from v1.x/v2?

pyve doctor and pyve validate were replaced by pyve check (diagnostics) and pyve status (read-only snapshot).

Common Workflows

Creating a New Python Project

# Create project directory
mkdir my-new-project
cd my-new-project

# Initialize, pinning a specific Python version
pyve init --python-version 3.14.5

# Install packages
pip install requests pytest

# Save dependencies
pip freeze > requirements.txt

Working with Existing Projects

# Clone repository
git clone https://github.com/user/project.git
cd project

# Initialize Pyve (reads .python-version if present)
pyve init

# Install dependencies
pip install -r requirements.txt

Switching Python Versions

# Pin a new Python version (writes .tool-versions / .python-version)
pyve python set 3.12.0

# Verify new version
pyve python show
python --version

Using Micromamba Backend

For projects with conda dependencies, the fastest path is to let pyve init scaffold a starter environment.yml for you:

# 1. In a fresh directory, just run init with the micromamba backend.
#    Pyve scaffolds a minimal environment.yml (python + pip, conda-forge)
#    and creates the micromamba environment in one step.
mkdir myproject && cd myproject
pyve init --backend micromamba --python-version 3.12.13

# 2. Edit the scaffolded environment.yml to add your real dependencies.
#    The default scaffold pins only python=<version> and pip.
$EDITOR environment.yml

# 3. Generate conda-lock.yml once you're happy with environment.yml.
pyve lock

# 4. Install any additional conda packages (or run `pyve lock` again).
micromamba install -c conda-forge scipy

Scaffolding contract. Pyve only scaffolds when both environment.yml and conda-lock.yml are absent — a clear signal that this is a fresh project. It never overwrites an existing environment.yml. Under --strict, scaffolding is disabled (hand-authored files only).

Already have an environment.yml? Skip the scaffold — pyve init will use your file as-is:

# Existing project with environment.yml that declares conda-lock (no lock yet):
pyve init --backend micromamba             # proceeds, then nudges you to run pyve lock
pyve lock                                   # generate the lock file when ready

# Existing project with both files:
pyve init --backend micromamba             # uses the lock file for reproducibility

Note: Whether pyve init --backend micromamba requires a lock is declarative — it depends on whether conda-lock is a dependency in environment.yml. If it is and no conda-lock.yml exists yet, non-strict init proceeds and nudges you to run pyve lock; --strict errors instead. If conda-lock isn't declared, no lock is expected. Pass --no-lock to skip the lock for a run (resolve from environment.yml; a present lock is ignored, never deleted), or remove conda-lock from environment.yml to opt out permanently.

Keeping the Environment Current

Three verbs, one meaning each:

pyve update            # refresh the files Pyve manages around the project (never touches an env)
pyve upgrade           # re-resolve the env's dependencies to newest-within-constraints, in place
pyve init --force      # destructive rebuild of the root env from the manifest

pyve upgrade --check previews the plan without executing anything. See Project Lifecycle for details.

Cleaning Up

Remove the virtual environment:

pyve purge

This removes:

  • Virtual environment directory
  • .envrc file
  • Pyve-managed .gitignore entries

Next Steps

Troubleshooting

Project Inside a Cloud-Synced Directory

If pyve init fails with ERROR: Project is inside a cloud-synced directory, move the project out of ~/Documents, ~/Desktop, ~/Dropbox, ~/Google Drive, or ~/OneDrive:

mv ~/Documents/myproject ~/Developer/myproject
cd ~/Developer/myproject
pyve init

Environment Not Activating

If direnv isn't activating automatically:

# Check direnv is installed and hooked
direnv version

# Allow the .envrc file
direnv allow

Python Version Not Found

If Pyve can't find the requested Python version:

# Install with asdf
asdf install python 3.11.0
asdf global python 3.11.0

# Or with pyenv
pyenv install 3.11.0
pyenv global 3.11.0

Command Not Found

If pyve command isn't found after installation:

# For Homebrew installation, verify it's in PATH
which pyve

# For manual installation, ensure ~/.local/bin is in PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

For more help, run:

pyve --help

Or check the full documentation.