envs Module

paraview.envs - virtual environments manager for ParaView’s Python

ParaView ships its own bundled Python interpreter, which makes it hard to pip-install extra packages (e.g. trame, custom apps) without touching the ParaView install itself. This module uses uv to create separate virtual environments and layers their site-packages on top of pvpython’s own sys.path, so scripts can import paraview (and its C++ bindings) and whatever was pip-installed in the venv.

Environments are stored under

~/.config/ParaView/uv-venvs/<python-version>/<name>/

Commands

list: List every environment that has been created or installed:

$ pvpython -m paraview.envs list

create: Create a named venv from a requirements.txt (does not run anything):

$ pvpython -m paraview.envs create trame ./requirements.txt

use: Enter a venv created with create and run a script provided after –:

$ pvpython -m paraview.envs use trame – ./example.py [args…]

install: Install a script as a named, reusable application. Its dependencies are

declared as PEP 723 inline metadata (lines starting with # at the top of the file, e.g. # dependencies = […]) and installed via uv run. –name defaults to the file’s stem; –replace overwrites an existing environment of the same name;

$ pvpython -m paraview.envs install ./cone.py [–name cone] [–replace]

run: Run a previously installed application by name. Add –enable-ssl if ssl is

required. –enable-ssl starts a new Python interpreter directly from the virtual environment and add ParaView environment on top of it:

$ pvpython -m paraview.envs run cone [–enable-ssl]

remove: Delete an environment (install or create) and its venv:

$ pvpython -m paraview.envs remove cone

Main commands are: list / create / use / install / run / remove

Run pvpython -m paraview.envs <command> –help for a command’s full options.

paraview.envs.build_parser()

Build the pvpython -m paraview.envs argument parser: one subcommand per top-level command (list/create/use/install/run/remove), each documented via argparse’s own –help rather than hand-written usage strings. See the module docstring for the full command reference.

paraview.envs.create(name, requirement)

Create a named venv named name and uv pip install -r requirement.

Unlike install(), this doesn’t copy or run any script - it just prepares an environment meant to be entered later with use <name> to run arbitrary scripts. Fails without side effects if requirement doesn’t exist or an environment named name already exists.

paraview.envs.find_uv_exec()

Locate the uv executable, caching the result on disk.

Looks up UV_EXEC_CACHE first; if missing or stale, walks up from sys.executable (pvpython) up to 3 parent directories and searches each subtree for a uv binary, since uv is typically bundled alongside or near the ParaView Python install.

paraview.envs.install(app, name, replace)

Install app (a .py file) as a persistent, named application.

Copies app into a new workspace as app.py, extracts its leading #-comment lines (PEP 723 inline script metadata, e.g. # dependencies = […]) into dependencies.py, creates a fresh venv, and runs uv run on dependencies.py so uv resolves and installs those dependencies into the venv. The app can later be launched with run <name>. Fails without side effects if app doesn’t exist or an environment named name already exists (unless replace=True).

paraview.envs.list_apps()

Print the names of all environments (install or create) on disk.

paraview.envs.load_venv(venv_base)

Graft a venv onto the current, already-running pvpython process.

Unlike a normal venv activation, this doesn’t spawn a new interpreter: it prepends the venv’s bin to PATH and adds its site-packages to sys.path, so packages pip-installed in the venv become importable alongside ParaView’s own bundled modules in this same process. site.addsitedir() appends new entries to the end of sys.path, so they are moved back to the front afterwards to make the venv take priority over pvpython’s built-ins when both provide the same package.

paraview.envs.main()

Parse sys.argv for one of the top-level commands (list, create, use, install, run, remove) and dispatch to it. Anything left over after a known command and its own options are parsed (e.g. the script and args following use <name> –, or extra args after run <name>) is passed through untouched, so it never has to survive being re-parsed by whatever argument parsing the invoked script/app does on its own.

paraview.envs.paraview_env()

Build an environment dict that exposes ParaView’s Python modules (PYTHONPATH) to a separate Python process, e.g. the standalone interpreter spawned by run(…, enable_ssl=True). This is only needed for code paths that run outside of the current pvpython process, since in-process execution already has ParaView on sys.path.

paraview.envs.remove(name)

Delete the environment (venv + app/dependency files) named name.

paraview.envs.run(name, enable_ssl, extra_args)

Launch a previously install-ed application by name.

By default the app’s app.py is loaded and its main() executed in-process, after grafting the app’s venv onto pvpython via load_venv(). With enable_ssl=True, the app is instead launched as a standalone subprocess using the venv’s own python, with ParaView’s modules injected via PYTHONPATH (see paraview_env()); this is needed because some apps (e.g. ones starting their own SSL/HTTPS server) must own their process rather than share pvpython’s. extra_args (anything following run <name> on the command line) is passed through to the app.

paraview.envs.use_venv(name, script_args)

Graft the venv name (built with create) onto pvpython, then run the script in script_args[0] in-process, with script_args[1:] left in sys.argv for the script to read.