use

Set a virtual environment for the current directory and activate it.

Usage

scoop use <name> [options]
scoop use system [options]
scoop use --unset [options]

Arguments

Options

Behavior

• Creates .scoop-version file in current directory
• Immediately activates the environment (if shell hook installed)
• With --global: writes to ~/.scoop/version
• With --link: creates .venv -> ~/.scoop/virtualenvs/<name>

Special Value: system

Using system as the name tells scoop to use the system Python:

scoop use system           # Use system Python in this directory
scoop use system --global  # Use system Python as global default

This writes the literal string system to the version file, which the shell hook interprets as “deactivate any virtual environment.”

The --unset Flag

Removes the version file entirely:

scoop use --unset           # Delete .scoop-version in current directory
scoop use --unset --global  # Delete ~/.scoop/version

After unsetting, scoop falls back to the next priority level in version resolution.

Examples

# Use a virtual environment in this directory
scoop use myproject

# Also create .venv symlink (for IDE support)
scoop use myproject --link

# Set global default environment
scoop use myproject --global

# Use system Python in this directory
scoop use system

# Use system Python globally
scoop use system --global

# Remove local version setting
scoop use --unset

# Remove global version setting
scoop use --unset --global

Set Python 3.11.0 as Global Default

--global stores an environment name, not a raw Python version string. Create an environment with Python 3.11.0, then set that environment globally:

scoop install 3.11.0
scoop create py311 3.11.0
scoop use py311 --global

This writes py311 to ~/.scoop/version, which is used in new shell sessions and directories that do not have a local .scoop-version.

If a local .scoop-version file or SCOOP_VERSION environment variable is present, it takes precedence over the global setting.

Version File Format

The .scoop-version file contains a single line with either:

• An environment name (e.g., myproject)
• The literal string system

$ cat .scoop-version
myproject