Command line interface

uv-workon

Manage uv virtual environments from central location.

uv-workon [OPTIONS] COMMAND [ARGS]...

Options

-v, --version

--install-completion

Install completion for the current shell.

--show-completion

Show completion for the current shell, to copy it or customize the installation.

activate

Use to activate virtual environments.

uv-workon activate [OPTIONS]

Options

-n, --name <venv_name>

Use virtual environment located at ${workon_home}/{name}.

-p, --path <venv_path>

Path to venv

--resolve, --no-resolve

Pass --resolve to resolve paths and symlinks. Otherwise, use relative paths.

Default:

False

--command, --no-command

If --command, include command name with output. If --no-command, only list the path.

Default:

False

-o, --workon-home <workon_home>

Directory containing the virtual environments and links to virtual environments. If not passed, uses in order, WORKON_HOME environment variable, then ~/.virtualenvs directory.

--venv <venv_patterns>

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.

--default-venv, --no-default-venv

Default is to include virtual environment patterns ".venv" and "venv". Pass --no-default-venv to exclude these default values.

Default:

True

Environment variables

WORKON_HOME

Provide a default for --workon-home

UV_WORKON_VENV_PATTERNS

Provide a default for --venv

cd

Command to change to parent directory of virtual environment.

uv-workon cd [OPTIONS]

Options

-n, --name <venv_name>

Use virtual environment located at ${workon_home}/{name}.

-p, --path <venv_path>

Path to venv

--command, --no-command

If --command, include command name with output. If --no-command, only list the path.

Default:

False

-o, --workon-home <workon_home>

Directory containing the virtual environments and links to virtual environments. If not passed, uses in order, WORKON_HOME environment variable, then ~/.virtualenvs directory.

--venv <venv_patterns>

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.

--default-venv, --no-default-venv

Default is to include virtual environment patterns ".venv" and "venv". Pass --no-default-venv to exclude these default values.

Default:

True

Environment variables

WORKON_HOME

Provide a default for --workon-home

UV_WORKON_VENV_PATTERNS

Provide a default for --venv

clean

Remove missing broken virtual environment symlinks.

uv-workon clean [OPTIONS]

Options

-o, --workon-home <workon_home>

Directory containing the virtual environments and links to virtual environments. If not passed, uses in order, WORKON_HOME environment variable, then ~/.virtualenvs directory.

--dry-run, --no-dry-run

Perform a dry run, without executing any action

Default:

False

-v, --verbose

Set verbosity level. Can specify multiple times

--yes, --no

Default is confirm yes/No for actions. Passing --yes confirms all answers as yes. Passing --no confirms all answers as no.

Environment variables

WORKON_HOME

Provide a default for --workon-home

kernels

Jupyter kernel utilities

uv-workon kernels [OPTIONS] COMMAND [ARGS]...

install

Install ipykernels for virtual environment(s) that contain ipykernel module.

uv-workon kernels install [OPTIONS]

Options

-n, --name <venv_names>

Virtual environment names.

-p, --path <venv_paths>

Virtual environment paths.

--all

If passed, install for all environments

Default:

False

--display-format <display_format>

Format to use in display name. Can contain name which is inferred from the virtual environment location.

Default:

'Python [venv: {name}]'

--user, --no-user

Default is to pass the --user options. Use this to override.

Default:

False

--resolve, --no-resolve

Pass --resolve to resolve paths and symlinks. Otherwise, use relative paths.

Default:

True

-o, --workon-home <workon_home>

Directory containing the virtual environments and links to virtual environments. If not passed, uses in order, WORKON_HOME environment variable, then ~/.virtualenvs directory.

--venv <venv_patterns>

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.

--default-venv, --no-default-venv

Default is to include virtual environment patterns ".venv" and "venv". Pass --no-default-venv to exclude these default values.

Default:

True

--dry-run, --no-dry-run

Perform a dry run, without executing any action

Default:

False

-v, --verbose

Set verbosity level. Can specify multiple times

--yes, --no

Default is confirm yes/No for actions. Passing --yes confirms all answers as yes. Passing --no confirms all answers as no.

Environment variables

WORKON_HOME

Provide a default for --workon-home

UV_WORKON_VENV_PATTERNS

Provide a default for --venv

list

List installed kernels. Interface to jupyter kernelspec list.

uv-workon kernels list [OPTIONS]

remove

Remove installed kernels

uv-workon kernels remove [OPTIONS]

Options

-n, --name <names>

Kernel names to remove

-p, --path <venv_paths>

Virtual environment paths.

--missing

Remove kernelspecs that are missing/broken.

Default:

False

-o, --workon-home <workon_home>

Directory containing the virtual environments and links to virtual environments. If not passed, uses in order, WORKON_HOME environment variable, then ~/.virtualenvs directory.

--venv <venv_patterns>

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.

--default-venv, --no-default-venv

Default is to include virtual environment patterns ".venv" and "venv". Pass --no-default-venv to exclude these default values.

Default:

True

--dry-run, --no-dry-run

Perform a dry run, without executing any action

Default:

False

-v, --verbose

Set verbosity level. Can specify multiple times

--yes, --no

Default is confirm yes/No for actions. Passing --yes confirms all answers as yes. Passing --no confirms all answers as no.

Environment variables

WORKON_HOME

Provide a default for --workon-home

UV_WORKON_VENV_PATTERNS

Provide a default for --venv

link

Create symlink from paths to workon_home.

uv-workon link [OPTIONS] [PATHS]...

Options

--parent <parents>

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-name <link_names>

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-resolve

Pass --resolve to resolve paths and symlinks. Otherwise, use relative paths.

Default:

False

-o, --workon-home <workon_home>

Directory containing the virtual environments and links to virtual environments. If not passed, uses in order, WORKON_HOME environment variable, then ~/.virtualenvs directory.

--venv <venv_patterns>

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.

--default-venv, --no-default-venv

Default is to include virtual environment patterns ".venv" and "venv". Pass --no-default-venv to exclude these default values.

Default:

True

--dry-run, --no-dry-run

Perform a dry run, without executing any action

Default:

False

-v, --verbose

Set verbosity level. Can specify multiple times

--yes, --no

Default is confirm yes/No for actions. Passing --yes confirms all answers as yes. Passing --no confirms all answers as no.

Arguments

PATHS

Optional argument(s)

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.

Environment variables

UV_WORKON_PATHS

Provide a default for PATHS

WORKON_HOME

Provide a default for --workon-home

UV_WORKON_VENV_PATTERNS

Provide a default for --venv

list

List available central virtual environments

uv-workon list [OPTIONS]

Options

-o, --workon-home <workon_home>

Directory containing the virtual environments and links to virtual environments. If not passed, uses in order, WORKON_HOME environment variable, then ~/.virtualenvs directory.

-v, --verbose

Set verbosity level. Can specify multiple times

Environment variables

WORKON_HOME

Provide a default for --workon-home

run

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.

uv-workon run [OPTIONS]

Options

-n, --name <venv_name>

Use virtual environment located at ${workon_home}/{name}.

-p, --path <venv_path>

Path to venv

--resolve, --no-resolve

Pass --resolve to resolve paths and symlinks. Otherwise, use relative paths.

Default:

True

-o, --workon-home <workon_home>

Directory containing the virtual environments and links to virtual environments. If not passed, uses in order, WORKON_HOME environment variable, then ~/.virtualenvs directory.

--venv <venv_patterns>

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.

--default-venv, --no-default-venv

Default is to include virtual environment patterns ".venv" and "venv". Pass --no-default-venv to exclude these default values.

Default:

True

--dry-run, --no-dry-run

Perform a dry run, without executing any action

Default:

False

-v, --verbose

Set verbosity level. Can specify multiple times

Environment variables

WORKON_HOME

Provide a default for --workon-home

UV_WORKON_VENV_PATTERNS

Provide a default for --venv

shell-config

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.

uv-workon shell-config [OPTIONS]

venv-link

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.

uv-workon venv-link [OPTIONS] [DESTINATION]

Options

-n, --name <venv_name>

Use virtual environment located at ${workon_home}/{name}.

-p, --path <venv_path>

Path to venv

--resolve, --no-resolve

Pass --resolve to resolve paths and symlinks. Otherwise, use relative paths.

Default:

False

-o, --workon-home <workon_home>

Directory containing the virtual environments and links to virtual environments. If not passed, uses in order, WORKON_HOME environment variable, then ~/.virtualenvs directory.

--venv <venv_patterns>

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.

--default-venv, --no-default-venv

Default is to include virtual environment patterns ".venv" and "venv". Pass --no-default-venv to exclude these default values.

Default:

True

--dry-run, --no-dry-run

Perform a dry run, without executing any action

Default:

False

-v, --verbose

Set verbosity level. Can specify multiple times

--yes, --no

Default is confirm yes/No for actions. Passing --yes confirms all answers as yes. Passing --no confirms all answers as no.

Arguments

DESTINATION

Optional argument

Path of linked virtual environment

Environment variables

WORKON_HOME

Provide a default for --workon-home

UV_WORKON_VENV_PATTERNS

Provide a default for --venv