Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Shell Integration

scuv uses a shell wrapper pattern (like pyenv) where the CLI outputs shell code that gets evaluated by the shell. scuv use itself only writes the version file; the wrapper then evaluates scuv activate (or deactivate for system).

How It Works

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ User runs    │ --> │ CLI outputs  │ --> │ Shell evals  │
│ scuv activate│     │ export ...   │     │ the output   │
└──────────────┘     └──────────────┘     └──────────────┘

The scuv shell function wraps the CLI binary (simplified; the real one also passes help flags through and respects an explicit --shell):

scuv() {
    case "$1" in
        use)
            command scuv "$@" || return
            local name=""
            shift
            for arg in "$@"; do
                case "$arg" in
                    -*) ;;
                    *) name="$arg"; break ;;
                esac
            done
            if [[ "$name" == [Ss][Yy][Ss][Tt][Ee][Mm] ]]; then
                eval "$(command scuv deactivate --shell bash)"
            elif [[ -n "$name" ]]; then
                eval "$(command scuv activate --shell bash "$name")"
            fi
            ;;
        activate|deactivate|shell)
            # Capture first, so a failed call keeps its exit status
            local script
            script="$(command scuv "$1" --shell bash "${@:2}")" || return
            eval "$script"
            ;;
        *)
            command scuv "$@"
            ;;
    esac
}

Setup

Zsh

echo 'eval "$(scuv init zsh)"' >> ~/.zshrc
source ~/.zshrc

Bash

echo 'eval "$(scuv init bash)"' >> ~/.bashrc
source ~/.bashrc

Fish

echo 'scuv init fish | source' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

PowerShell

# Add to $PROFILE
Add-Content $PROFILE 'Invoke-Expression (& scuv init powershell | Out-String)'
# Restart PowerShell

Keep the | Out-String: scuv init powershell prints many lines, and Invoke-Expression takes one string, not the array of lines & returns. A profile line without it never defines the scuv function; if yours lacks it, update the line.

Auto-Activation

When enabled, scuv automatically activates environments based on version files.

Zsh: Uses chpwd hook (runs on directory change)

autoload -Uz add-zsh-hook
add-zsh-hook chpwd _scuv_hook

Bash: Uses PROMPT_COMMAND, through one entry added the first time and never edited

PROMPT_COMMAND="_scuv_hook;$PROMPT_COMMAND"   # _scuv_hook does nothing while auto-activation is off

Fish: Uses --on-variable PWD event handler

function _scuv_hook
    # Check for version file and activate/deactivate
end

function _scuv_on_pwd --on-variable PWD
    _scuv_hook
end

The hook checks for version files and activates/deactivates accordingly.

Version Resolution Priority

scuv checks these sources in order (first match wins):

PrioritySourceSet by
1SCUV_VERSION env varscuv shell
2.scuv-version filescuv use (walks parent directories)
3~/.scuv/version filescuv use --global

The “system” Value

When any source contains the value system, scuv deactivates the current virtual environment and uses the system Python.

scuv use system          # Write "system" to .scuv-version
scuv shell system        # Set SCUV_VERSION=system (this terminal only)

Environment Variables

VariableDescriptionDefault
SCUV_HOMEBase directory~/.scuv
SCUV_VERSIONOverride version (highest priority)(unset)
SCUV_NO_AUTORead at scuv init; see Disable Auto-Activation(unset)
SCUV_ACTIVECurrently active environment(set by scuv)
SCUV_RESOLVE_MAX_DEPTHLimit parent directory traversal(unlimited)

Disable Auto-Activation

SCUV_NO_AUTO is read once, when your shell sources scuv init, so set it to a non-empty value before the scuv init line in your rc file:

export SCUV_NO_AUTO=1
eval "$(scuv init bash)"

It turns off both automatic activations in every shell: the one when the shell starts and the one when you change directory (bash and PowerShell check on each prompt, zsh and fish on each cd). An empty value counts as unset. scuv activate, scuv use and scuv shell still work.

Changing the variable in a running shell takes effect when the init script is sourced again (source ~/.zshrc, for example), which also turns off the hook the earlier sourcing added. Up to scuv 0.18.1 the variable turned off only one of the two, and which one depended on the shell.

Temporary and Project-Scoped Control

Stop activation in the current shell session only (does not affect global settings):

scuv shell system
# ...work without auto-activation...
scuv shell --unset

For one project directory, use local version files instead of global settings:

cd ~/project

# Keep auto-activation, but force system Python in this project only
scuv use system

# Or pin a specific environment for this project only
scuv use myproject

For temporary per-terminal overrides without changing files:

scuv shell system    # this terminal only
# ...test...
scuv shell --unset   # return to file-based behavior

Custom Home Directory

export SCUV_HOME=/custom/path

Network Filesystem Optimization

For slow network filesystems (NFS, SSHFS), limit directory traversal depth:

# Only check current directory and up to 3 parents
export SCUV_RESOLVE_MAX_DEPTH=3

# Only check current directory (fastest)
export SCUV_RESOLVE_MAX_DEPTH=0

Using with pyenv

Add scuv after pyenv in your shell config:

# ~/.zshrc
eval "$(pyenv init -)"       # 1. pyenv first
eval "$(scuv init zsh)"     # 2. scuv second (takes precedence)

Tab Completion

Shell integration includes completion for:

  • Commands and subcommands
  • Environment names
  • Python versions
  • Command options

Completion is automatically enabled by scuv init.

Supported Shells

ShellStatus
ZshFull support (auto-activation, completion)
BashFull support (auto-activation, completion)
FishFull support (auto-activation, completion)
PowerShellFull support (auto-activation, completion)