pload

pload is a relocatable Python runtime and virtual-environment manager for Bash, Zsh, Fish, and PowerShell. Its private runtime, downloaded Python versions, virtual environments, registry, and caches can all live under directories you choose. pyenv is supported for discovery, but is not required.

Running pload without arguments opens a small welcome screen. Use -h for a complete parameter reference and -h -d for practical examples and effects.

Contents

• Install
• Reproduce and share environments
• Upgrade
• First run
• Configure later
• Shell activation
• Discover and install Python
• Create and activate environments
• Help and aliases
• Terminal experience
• Isolation and directory layout
• Command reference
• Development
• License

Install

Install the small bootstrap package, then start the guided installer:

python -m pip install --user --upgrade pload
python -m pload.installer

If your distribution enforces PEP 668, use pipx or a dedicated bootstrap virtual environment:

python3 -m venv ~/.pload-bootstrap
~/.pload-bootstrap/bin/python -m pip install --upgrade pload
~/.pload-bootstrap/bin/python -m pload.installer

On Windows, replace python with py when appropriate. If pipx is already available:

pipx install pload
pload-install

The installer uses consistent cursor-key choices for the pload data directory, launcher directory, virtual-environment directory, Python directory, runtime source, pip index, and optional shell integration. Use ↑/↓ to move and Enter to accept the highlighted value. Without a terminal UI, the same prompts fall back to numbered choices.

After installation it prints an ASCII welcome screen with copyable next steps. The same screen is shown whenever you run bare pload (see the screenshot at the top of this page).

For a non-interactive setup:

python -m pload.installer --yes \
  --home /mnt/tools/pload \
  --bin-dir ~/.local/bin \
  --venvs-dir /mnt/venvs \
  --python-dir /mnt/python \
  --source ustc \
  --pip-source tsinghua

--yes accepts explicit values and saved defaults. It only changes a shell profile when --shell is supplied or already configured.

Reproduce and share environments

The 1.2 preview uses one clean, user-authored pload.toml as portable intent. pload manages .pload_lock.toml (exact versions and artifacts) and .pload_plan.toml (the selected acquisition route for every package):

pload describe v2 -o pload.toml
pload plan pload.toml
pload apply pload.toml
pload apply --local         # reproduce into .venv beside pload.toml

plan fetches only index pages and independent package metadata—never wheel bodies—and inventories pload/pip/uv caches, compatible existing environments, local/SSH stores and indexes. Its interactive chooser shows only dependencies written by the user; transitive dependencies are routed automatically. It supports previous/next, undo, reset, save and save-and-apply through a compact shortcut row (p/n/u/r/s/a/q); the selection list itself contains only real package sources. apply executes exactly the saved plan: it never re-resolves, changes route, falls back, or uploads packages. Set [plan].mode = "auto" in pload.toml to save recommended routes without the chooser; strict per-package exceptions live under [plan.packages.NAME]. apply prints the saved plan first, then compact Docker-style progress rows. Each package is prefixed by its route, such as [cache], [index-exact], or [repository], followed only by its byte progress. Verbose grey source/status suffixes are intentionally omitted because the saved plan above already names the selected resource. The bar uses Rich's standard adaptive-width bar with explicit start and end boundaries, so it grows naturally on wider terminals without another progress dependency. Index and repository transfers report real received bytes at up to 30 updates per second. SSH repository downloads stream the remote object directly; cache routes report bytes while verifying SHA-256 instead of turning green before visible work. Environment-copy routes validate the source RECORD, then immediately stage each byte from the compatible environment and finish green before pload advances to the next package. The staged files are installed after the target environment exists. Redirected logs remain coalesced instead of flooding CI.

Use pload apply --local (or -l) for a project-local environment. It creates .venv beside the selected pload.toml, matching the layout produced by pload init while executing the saved declarative plan exactly.

Back up a special or slow wheel only when you explicitly request it:

pload remote add torch --from v10 --remote lab

See the declarative environment guide for the complete TOML field reference, exact versus compatible policies, resource-selection algorithm, CUDA wheel caching, idempotency and current platform boundaries.

Upgrade

Check the installed version first:

pload --version

For an installation managed by pload-install, upgrade the private runtime in place. Your configured directories, registry, downloaded Python runtimes, and virtual environments are kept:

pload-install --yes --package-spec "pload==1.0.0"

To opt into the declarative-environment pre-release for testing:

pload-install --yes --package-spec "pload==1.2.0b1"

To always follow the newest published release instead of pinning a version, omit the version constraint:

pload-install --yes --package-spec pload

If your selected mirror has not synchronized the release yet, choose the official index for this run (or replace it with another configured index):

pload-install --yes --package-spec "pload==1.0.0" --pip-index https://pypi.org/simple

For pipx installations use pipx's own upgrade command:

pipx upgrade pload

For a dedicated bootstrap virtual environment, run pip through that same interpreter:

~/.pload-bootstrap/bin/python -m pip install --upgrade pload

Verify the result and refresh shell integration if the current shell still has an older function loaded:

pload --version
pload cfg
eval "$(pload shell-init zsh)"   # use bash/fish/powershell as appropriate

On systems enforcing PEP 668, do not force-install into the system Python; use pipx or the dedicated bootstrap environment shown above.

First run

pload

The no-argument screen gives the shortest useful tour:

pload cfg                         # show effective paths and sources
pload python list                 # discover usable Python interpreters
pload new -n data -v 3.12         # create an environment
pload list                        # list IDs, descriptions, and paths
pload v1                          # activate an environment by ID

Run pload new without options to start the guided creator. It lists detected Python runtimes, then asks for the interpreter, environment name, description, and optional packages. When packages are present, choose Automatic to let pload prefer a compatible local wheel cache and otherwise use the configured index, or Custom to choose the source of each top-level package yourself. Press Enter to accept the suggested value at each step.

Configure later

Inspect the effective configuration:

pload cfg
pload config show

Change one value without reinstalling pload or uv:

pload cfg set source ustc
pload cfg set pip-source tsinghua
pload cfg set venvs-dir ~/venvs
pload cfg set python-dir ~/.pload/pythons
pload cfg set shell zsh

Reopen the complete setup wizard at any time:

pload cfg -t

The wizard reuses current values as defaults and updates configuration plus the selected shell profile. It does not reinstall pload, uv, or existing environments. Configuration is stored in PLOAD_HOME/config.json.

Shell activation

The installer can update a shell profile. To configure it manually:

# Bash
eval "$(pload shell-init bash)"

# Zsh
eval "$(pload shell-init zsh)"

# Fish
pload shell-init fish | source

PowerShell:

Invoke-Expression (& pload shell-init powershell | Out-String)

Then pload v1, pload data, and pload . can activate environments in the current shell.

Discover and install Python

pload python list scans usable interpreters from the operating system, PATH, uv, pyenv, Conda, mise, asdf, Homebrew, and the Windows Python Launcher. Duplicate executable paths are collapsed:

pload python list
pload python list --filter uv,conda
pload python list --filter uv conda
pload python path 3.12

Each distinct executable receives a stable Python ID and readable alias:

ID   ALIAS          VERSION  TYPE    PATH
py1  uv-v3.12.8     3.12.8   uv      ~/.pload/pythons/.../python3.12
py2  conda-v3.11.9  3.11.9   conda   ~/miniforge3/envs/data/bin/python

The ID and alias are separate columns in the real output:

Use any of these forms when selecting an interpreter:

pload new -n data --version py1
pload new -n data --version uv-v3.12.8
pload new -n data --version py1:uv-v3.12.8
pload python path py1

Types include sys, pyenv, uv, conda, mise, asdf, homebrew, and other. Compatibility names system and managed map to sys and uv.

Install a managed Python without pyenv:

pload python install 3.12
pload python install 3.13.3

Managed runtimes are stored under the configured Python directory and do not replace /usr/bin/python, Homebrew, pyenv, or Conda installations.

Runtime downloads and Python package downloads are configured separately:

• runtime source: official, ustc, or custom;
• pip source: official, tsinghua, ustc, aliyun, or custom.

The runtime source controls uv's python-build-standalone archives. A normal PyPI mirror does not host those archives.

Create and activate environments

Create a named environment with a description:

pload new                     # guided creation
pload new -n data -v 3.12 -m "Data analysis"
pload new -n web -v 3.12 -r fastapi uvicorn -m "Web API"
pload new -n lab -r numpy torch -s custom  # choose each top-level package source
pload new -v 3.12 --message "Temporary data tools"  # auto-named safely
pload list
pload v1

Create a project-local environment:

pload init -m "Current project"
pload .
pload init -r pytest requests

Use an explicit interpreter or destination when needed:

pload new -p /mnt/venvs/build -v /opt/python/bin/python
pload init -P /mnt/projects/app -e /mnt/venvs/app

Every managed environment receives an ID such as v1, v2, or v3, plus a description and creation timestamp. Deleted IDs are reused from the first available number. pload list displays environments newest-first:

The table includes ID, name, Python version, description, and full path. A spinner is shown in interactive terminals; redirected and CI output uses stable ordinary log lines.

Package requests are installed one at a time. A misspelled, unavailable, or invalid request is reported and skipped, while later requests still run and successful installations remain in the environment. The command returns a failure status at the end when any requested package failed, with one summary listing those packages. Source selection applies only to packages explicitly entered by the user; pip continues to resolve their transitive dependencies.

Help and aliases

Brief help is a complete reference. It starts with an emphasized USAGE panel, then lists every positional argument, long option, short alias, and description:

pload config -h
pload cfg -h
pload new -h
pload py install -h
pload py ls -h
pload-install -h

The root help keeps global storage options together, while command-specific help shows only that command's arguments:

Detailed help adds examples, expected output, disk effects, and failure behavior:

pload -h -d
pload new -h -d
pload cfg -h -d
pload py ls -h -d
pload-install -h -d

Command aliases:

Command	Alias
new	none; already short and explicit
init	i
list	ls
rm	remove, del, delete
python	py
path	p
config	cfg
shell-init	shell

Python subcommands use ls and p; the explicit install command has no alias:

pload py ls --filter uv,conda
pload python install 3.12
pload py p 3.12

Terminal experience

All interactive screens share the same keyboard and visual language. Use ↑/↓ and Enter in guided creation, setup, and package-route selection; recommended values start highlighted. Status, success, warning, and error messages use the same symbols and colors everywhere, while compact border-light tables keep lists readable.

NO_COLOR=1 disables color. PLOAD_NO_PROGRESS=1 replaces animated progress with plain status lines. Every guided workflow also has an explicit flag-based form for scripts. See the terminal experience specification for the complete interaction and output contract.

Isolation and directory layout

Put all pload-managed data under one root:

export PLOAD_HOME=/mnt/workspace/.pload
pload new -n tools

The default layout is:

PLOAD_HOME/
├── config.json       saved choices
├── runtime/          pload and uv private runtime
├── pythons/          downloaded Python runtimes
├── python-bin/       managed Python executable links
├── cache/python/     Python download cache
├── state/            environment IDs and Python runtime IDs
└── venvs/            managed virtual environments

Override individual roots with PLOAD_VENVS_DIR, PLOAD_STATE_DIR, or the global --home, --venvs-dir, and --state-dir options. Project-local environments can live elsewhere with init --project-dir and --venv-dir.

Command reference

pload new -h -d
pload init -h -d
pload list -h -d
pload rm -h -d
pload path -h -d
pload python -h -d
pload python install -h -d
pload python list -h -d
pload config -h -d
pload-install -h -d

Other useful commands:

pload path v1
pload rm v1 --yes
pload rm --expression '^test-' --yes
pload cfg set source ustc
pload cfg -t

Development

python -m pip install -e '.[test]'
pytest
ruff check src tests

License

Apache License 2.0. Copyright 2025 Yunming Hu.