pycontrol-manager

pycontrol-manager manages the lifecycle of the global pyControl application. It installs pycontrol-gui and the pycontrol CLI with uv, updates and uninstalls the app, switches between published and editable sources, manages optional dependencies, and creates the OS launcher.

Workspace creation and experiment operation are deliberately outside the manager. Create or open a workspace in the GUI, or use pycontrol workspace.

Quickstart

Install uv 0.8.5 or newer (uv self update upgrades an existing copy), then install the manager:

uv tool install --prerelease if-necessary-or-explicit pycontrol-manager

Install the app, verify the installation, then launch it. app install and app update run pycontrol-gui --version after installing and fail if the GUI does not start:

pycontrol-manager app install
pycontrol-manager app status
pycontrol gui

pycontrol gui opens a workspace containing the current directory when one is available. Otherwise, it opens the last valid workspace remembered by the GUI. On the first launch outside a workspace, with nothing remembered, it shows the welcome dialog so you can create or open one. Pass pycontrol gui PATH to override that selection for one launch.

The app is installed once per computer and can switch among plain-data workspaces.

Application lifecycle

pycontrol-manager app install
pycontrol-manager app update
pycontrol-manager app status
pycontrol-manager app uninstall

app install is safe to repeat. It preserves the current published or editable source mode and all enabled extras. app update installs the newest published packages and refuses to replace editable local sources.

app uninstall removes the pycontrol-gui uv tool environment, the OS shortcut (including the Windows icon file), and GUI preferences. If the GUI can no longer start to clear its own preferences, the uninstall warns and continues. It leaves pycontrol-manager installed for diagnostics or a future reinstall. Remove the manager separately when it is no longer needed:

uv tool uninstall pycontrol-manager

Published and local sources

Switch the app to editable sibling pycontrol-core/ and pycontrol-gui/ checkouts:

pycontrol-manager app source local /path/to/source-root

Source edits are immediately live in the global commands and OS launcher. Switch back to the newest published packages with:

pycontrol-manager app source pypi

Optional dependencies

Available extras are analysis, notion, s3, and slack.

pycontrol-manager app extras list
pycontrol-manager app extras add slack notion
pycontrol-manager app extras add integrations
pycontrol-manager app extras remove s3

integrations expands to notion, s3, and slack. Extras are installed into the global app environment and preserved across installs, updates, and source switches.

Status and diagnostics

app status reports installed core and GUI versions, Python, source mode, enabled extras, executable paths, and shortcut state:

pycontrol-manager app status

Run read-only installation diagnostics with:

pycontrol-manager doctor

The doctor checks uv, the tool receipt, editable source paths, package versions, command location, and shortcut state. It does not modify the installation.

Installation options

Commands that install or rebuild the app accept:

--python PYTHON
--prerelease {allow,disallow,if-necessary,explicit,if-necessary-or-explicit}
--index-url URL
--extra-index-url URL

Index URLs can also be supplied through PYCONTROL_MANAGER_INDEX_URL and PYCONTROL_MANAGER_EXTRA_INDEX_URL.

app install additionally accepts --shortcut and --no-shortcut.

Development

Install this checkout as an editable tool:

uv tool install --editable /path/to/pycontrol-manager

Run checks:

uv sync --group dev
uv run pytest
uv run ruff check src tests