Command line interface# uv-workon# uv-workon Usage: uv-workon [OPTIONS] COMMAND [ARGS]... Manage uv virtual environments from central location. ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮ │--version-v│ │--install-completionInstall completion for the current shell.│ │--show-completionShow completion for the current shell, to copy it or customize │ │the installation. │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────╮ │link Create symlink from paths to workon_home. │ │list List available central virtual environments │ │clean Remove missing broken virtual environment symlinks. │ │run Run uv commands using using the named or specified virtual environment. │ │venv-link Create symlink from virtual environment to a local ``.venv`` │ │shell-configUse with ``eval "$(uv-workon shell-config)"`` or ``uv-workon shell-config | │ │source`` for fish shell. │ │activate Use to activate virtual environments. │ │cd Command to change to parent directory of virtual environment. │ │kernels Jupyter kernel utilities │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ link# link Usage: uv-workon link [OPTIONS] [PATHS]... Create symlink from paths to workon_home. ╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────╮ │paths[PATHS]...Paths to virtual environments. These can either be full paths to │ │virtual environments, or path to the parent of a virtual environment │ │that has name ``venv_pattern``. If the name (the last element) of the │ │path matches ``venv_pattern``, then the name of the linked virtual │ │environment will come from the parent directory. Otherwise, it will be │ │the name. │ │[env var: UV_WORKON_PATHS] │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮ │--parentPATH Parent of directories to check for │ │``venv_pattern`` directories containing │ │virtual environments. Using ``uv-workon │ │--parent a/path`` is roughly equivalent to │ │using ``uv-workon a/path/*`` │ │--link-nameTEXT Name of the linked virtual environment. │ │Default is to infer the name from path. Can │ │specify multiple times. If use this option, it│ │must match up with the number of paths. It is │ │intended to be used once only. Use with care │ │in other cases. │ │--resolve--no-resolvePass ``--resolve`` to resolve paths and │ │symlinks. Otherwise, use relative paths. │ │[default: no-resolve] │ │--workon-home-oPATH Directory containing the virtual environments │ │and links to virtual environments. If not │ │passed, uses in order, ``WORKON_HOME`` │ │environment variable, then ``~/.virtualenvs`` │ │directory. │ │[env var: WORKON_HOME] │ │--venvTEXT Virtual environment pattern. Can specify │ │multiple times. Default is to include virtual │ │environment directories of form ``".venv"`` or│ │``"venv"``. To exclude these defaults, pass │ │``--no-default-venv``. │ │[env var: UV_WORKON_VENV_PATTERNS] │ │--default-venv--no-default-venvDefault is to include virtual environment │ │patterns ``".venv"`` and ``"venv"``. Pass │ │``--no-default-venv`` to exclude these default│ │values. │ │[default: default-venv] │ │--dry-run--no-dry-runPerform a dry run, without executing any │ │action │ │[default: no-dry-run] │ │--verbose-vINTEGERSet verbosity level. Can specify multiple │ │times │ │--yes--noDefault is confirm yes/No for actions. Passing│ │``--yes`` confirms all answers as yes. Passing│ │``--no`` confirms all answers as no. │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ list# list Usage: uv-workon list [OPTIONS] List available central virtual environments ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮ │--workon-home-oPATH Directory containing the virtual environments and links to │ │virtual environments. If not passed, uses in order, │ │``WORKON_HOME`` environment variable, then ``~/.virtualenvs`` │ │directory. │ │[env var: WORKON_HOME] │ │--verbose-vINTEGERSet verbosity level. Can specify multiple times│ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ clean# clean Usage: uv-workon clean [OPTIONS] Remove missing broken virtual environment symlinks. ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮ │--workon-home-oPATH Directory containing the virtual environments and │ │links to virtual environments. If not passed, uses │ │in order, ``WORKON_HOME`` environment variable, then│ │``~/.virtualenvs`` directory. │ │[env var: WORKON_HOME] │ │--dry-run--no-dry-runPerform a dry run, without executing any action│ │[default: no-dry-run] │ │--verbose-vINTEGERSet verbosity level. Can specify multiple times│ │--yes--noDefault is confirm yes/No for actions. Passing │ │``--yes`` confirms all answers as yes. Passing │ │``--no`` confirms all answers as no. │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ run# run Usage: uv-workon run [OPTIONS] Run uv commands using using the named or specified virtual environment. For example, use ``uv-workon run -n my-env -- python ...`` is translated to ``uv run -p patt/to/my-env --no-project python ...``. If an option mirrors one of the command options (-n, etc), pass it after ``--``. Use ``--dry-run`` to echo the equivalent command to be run in the shell. Under the hood, this uses ``uv run`` with the environment variables ``VIRTUAL_ENV`` and ``UV_PROJECT_ENVIRONMENT`` and the option ``-p`` all set to the path of the virtual environment, and with the option ``--no-project``. ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮ │--name-nTEXT Use virtual environment located at │ │${workon_home}/{name}. │ │--path-pPATH Path to venv│ │--resolve--no-resolvePass ``--resolve`` to resolve paths and │ │symlinks. Otherwise, use relative paths. │ │[default: resolve] │ │--workon-home-oPATH Directory containing the virtual environments │ │and links to virtual environments. If not │ │passed, uses in order, ``WORKON_HOME`` │ │environment variable, then ``~/.virtualenvs`` │ │directory. │ │[env var: WORKON_HOME] │ │--venvTEXT Virtual environment pattern. Can specify │ │multiple times. Default is to include virtual │ │environment directories of form ``".venv"`` or│ │``"venv"``. To exclude these defaults, pass │ │``--no-default-venv``. │ │[env var: UV_WORKON_VENV_PATTERNS] │ │--default-venv--no-default-venvDefault is to include virtual environment │ │patterns ``".venv"`` and ``"venv"``. Pass │ │``--no-default-venv`` to exclude these default│ │values. │ │[default: default-venv] │ │--dry-run--no-dry-runPerform a dry run, without executing any │ │action │ │[default: no-dry-run] │ │--verbose-vINTEGERSet verbosity level. Can specify multiple │ │times │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ venv-link# venv-link Usage: uv-workon venv-link [OPTIONS] [DESTINATION] Create symlink from virtual environment to a local ``.venv`` This is, in a sense, the inverse of the ``link`` subcommand. While ``link`` links from a virtualenv to ``workon_home``, this links from ``workon_home`` to a local ``.venv``. This can then be used (with care) via ``uv run ...``. Note that this is experimental and subject to change. ╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────╮ │destination[DESTINATION]Path of linked virtual environment[default: (.venv)]│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮ │--name-nTEXT Use virtual environment located at │ │${workon_home}/{name}. │ │--path-pPATH Path to venv│ │--resolve--no-resolvePass ``--resolve`` to resolve paths and │ │symlinks. Otherwise, use relative paths. │ │[default: no-resolve] │ │--workon-home-oPATH Directory containing the virtual environments │ │and links to virtual environments. If not │ │passed, uses in order, ``WORKON_HOME`` │ │environment variable, then ``~/.virtualenvs`` │ │directory. │ │[env var: WORKON_HOME] │ │--venvTEXT Virtual environment pattern. Can specify │ │multiple times. Default is to include virtual │ │environment directories of form ``".venv"`` or│ │``"venv"``. To exclude these defaults, pass │ │``--no-default-venv``. │ │[env var: UV_WORKON_VENV_PATTERNS] │ │--default-venv--no-default-venvDefault is to include virtual environment │ │patterns ``".venv"`` and ``"venv"``. Pass │ │``--no-default-venv`` to exclude these default│ │values. │ │[default: default-venv] │ │--dry-run--no-dry-runPerform a dry run, without executing any │ │action │ │[default: no-dry-run] │ │--verbose-vINTEGERSet verbosity level. Can specify multiple │ │times │ │--yes--noDefault is confirm yes/No for actions. Passing│ │``--yes`` confirms all answers as yes. Passing│ │``--no`` confirms all answers as no. │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ shell-config# shell-config Usage: uv-workon shell-config [OPTIONS] Use with ``eval "$(uv-workon shell-config)"`` or ``uv-workon shell-config | source`` for fish shell. This will add the subcommand ``uv-workon activate`` and ``uv-workon cd`` to the shell. Without running shell config, ``activate`` and ``cd`` will just print the command to screen. ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ activate# activate Usage: uv-workon activate [OPTIONS] Use to activate virtual environments. ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮ │--name-nTEXTUse virtual environment located at │ │${workon_home}/{name}. │ │--path-pPATHPath to venv│ │--resolve--no-resolvePass ``--resolve`` to resolve paths and symlinks.│ │Otherwise, use relative paths. │ │[default: no-resolve] │ │--command--no-commandIf ``--command``, include command name with │ │output. If ``--no-command``, only list the path. │ │[default: no-command] │ │--workon-home-oPATHDirectory containing the virtual environments and│ │links to virtual environments. If not passed, │ │uses in order, ``WORKON_HOME`` environment │ │variable, then ``~/.virtualenvs`` directory. │ │[env var: WORKON_HOME] │ │--venvTEXTVirtual environment pattern. Can specify multiple│ │times. Default is to include virtual environment │ │directories of form ``".venv"`` or ``"venv"``. │ │To exclude these defaults, pass │ │``--no-default-venv``. │ │[env var: UV_WORKON_VENV_PATTERNS] │ │--default-venv--no-default-venvDefault is to include virtual environment │ │patterns ``".venv"`` and ``"venv"``. Pass │ │``--no-default-venv`` to exclude these default │ │values. │ │[default: default-venv] │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ cd# cd Usage: uv-workon cd [OPTIONS] Command to change to parent directory of virtual environment. ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮ │--name-nTEXTUse virtual environment located at │ │${workon_home}/{name}. │ │--path-pPATHPath to venv│ │--command--no-commandIf ``--command``, include command name with │ │output. If ``--no-command``, only list the path. │ │[default: no-command] │ │--workon-home-oPATHDirectory containing the virtual environments and│ │links to virtual environments. If not passed, │ │uses in order, ``WORKON_HOME`` environment │ │variable, then ``~/.virtualenvs`` directory. │ │[env var: WORKON_HOME] │ │--venvTEXTVirtual environment pattern. Can specify multiple│ │times. Default is to include virtual environment │ │directories of form ``".venv"`` or ``"venv"``. │ │To exclude these defaults, pass │ │``--no-default-venv``. │ │[env var: UV_WORKON_VENV_PATTERNS] │ │--default-venv--no-default-venvDefault is to include virtual environment │ │patterns ``".venv"`` and ``"venv"``. Pass │ │``--no-default-venv`` to exclude these default │ │values. │ │[default: default-venv] │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ kernels# kernels Usage: uv-workon kernels [OPTIONS] COMMAND [ARGS]... Jupyter kernel utilities ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────╮ │installInstall ipykernels for virtual environment(s) that contain ``ipykernel`` module. │ │remove Remove installed kernels │ │list List installed kernels. Interface to jupyter kernelspec list. │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ install# install Usage: uv-workon kernels install [OPTIONS] Install ipykernels for virtual environment(s) that contain ``ipykernel`` module. ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮ │--name-nTEXT Virtual environment names.│ │--path-pPATH Virtual environment paths.│ │--allIf passed, install for all environments│ │--display-formatTEXT Format to use in display name. Can contain │ │``name`` which is inferred from the virtual │ │environment location. │ │[default: Python [venv: {name}]] │ │--user--no-userDefault is to pass the ``--user`` options. │ │Use this to override. │ │[default: no-user] │ │--resolve--no-resolvePass ``--resolve`` to resolve paths and │ │symlinks. Otherwise, use relative paths. │ │[default: resolve] │ │--workon-home-oPATH Directory containing the virtual │ │environments and links to virtual │ │environments. If not passed, uses in order, │ │``WORKON_HOME`` environment variable, then │ │``~/.virtualenvs`` directory. │ │[env var: WORKON_HOME] │ │--venvTEXT Virtual environment pattern. Can specify │ │multiple times. Default is to include │ │virtual environment directories of form │ │``".venv"`` or ``"venv"``. To exclude these│ │defaults, pass ``--no-default-venv``. │ │[env var: UV_WORKON_VENV_PATTERNS] │ │--default-venv--no-default-venvDefault is to include virtual environment │ │patterns ``".venv"`` and ``"venv"``. Pass │ │``--no-default-venv`` to exclude these │ │default values. │ │[default: default-venv] │ │--dry-run--no-dry-runPerform a dry run, without executing any │ │action │ │[default: no-dry-run] │ │--verbose-vINTEGERSet verbosity level. Can specify multiple │ │times │ │--yes--noDefault is confirm yes/No for actions. │ │Passing ``--yes`` confirms all answers as │ │yes. Passing ``--no`` confirms all answers │ │as no. │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ remove# remove Usage: uv-workon kernels remove [OPTIONS] Remove installed kernels ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮ │--name-nTEXT Kernel names to remove│ │--path-pPATH Virtual environment paths.│ │--missingRemove kernelspecs that are missing/broken.│ │--workon-home-oPATH Directory containing the virtual environments │ │and links to virtual environments. If not │ │passed, uses in order, ``WORKON_HOME`` │ │environment variable, then ``~/.virtualenvs`` │ │directory. │ │[env var: WORKON_HOME] │ │--venvTEXT Virtual environment pattern. Can specify │ │multiple times. Default is to include virtual │ │environment directories of form ``".venv"`` or│ │``"venv"``. To exclude these defaults, pass │ │``--no-default-venv``. │ │[env var: UV_WORKON_VENV_PATTERNS] │ │--default-venv--no-default-venvDefault is to include virtual environment │ │patterns ``".venv"`` and ``"venv"``. Pass │ │``--no-default-venv`` to exclude these default│ │values. │ │[default: default-venv] │ │--dry-run--no-dry-runPerform a dry run, without executing any │ │action │ │[default: no-dry-run] │ │--verbose-vINTEGERSet verbosity level. Can specify multiple │ │times │ │--yes--noDefault is confirm yes/No for actions. Passing│ │``--yes`` confirms all answers as yes. Passing│ │``--no`` confirms all answers as no. │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ list# list Usage: uv-workon kernels list [OPTIONS] List installed kernels. Interface to jupyter kernelspec list. ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯