🍨 scuv

⚠️ Work in Progress — Under active development. API may change.

📢 Renamed in v0.15.0: the CLI command is now scuv (formerly scoop) — renamed to coexist with Scoop, the Windows package manager. The crate/repo keep the name scoop-uv. Legacy SCOOP_*/.scoop-* settings are still read (with a deprecation warning) until v0.16.0 — see the CHANGELOG for migration notes.

One scoop, endless envs — pyenv-style Python environment manager powered by uv

🍨 More badges

scuv scoops up uv's blazing speed — centralizing all your Python virtual environments in one place.

🍨 Think of it like running an ice cream parlor:

• The Freezer (~/.scuv/) keeps all your flavors fresh
• Flavors are your virtualenvs — mix once, serve anywhere
• One scoop is all you need to get the right env

# 1. Install prerequisites
curl -LsSf https://astral.sh/uv/install.sh | sh  # uv
cargo install scoop-uv                           # installs the scuv command

# 2. Initialize your shell (zsh example)
echo 'eval "$(scuv init zsh)"' >> ~/.zshrc && source ~/.zshrc

# 3. Create your first environment
scuv install 3.12
scuv create myproject 3.12

# 4. Use it (auto-activates when you enter the directory!)
scuv use myproject
(myproject) $ pip install -r requirements.txt

That's it! 🎉 Your environment is ready. For detailed docs, see Full Documentation →

Use this when you want new shell sessions to default to an environment built on Python 3.11.0:

scuv install 3.11.0
scuv create py311 3.11.0
scuv use py311 --global

This writes py311 to ~/.scuv/version. Priority still applies: SCUV_VERSION (shell override) and local .scuv-version take precedence.

Use this when you want a new project environment pinned to an exact Python patch version:

scuv install 3.9.5
scuv create myproject 3.9.5
scuv info myproject

If 3.9.5 is missing, check available versions with uv python list and scuv list --pythons, then install and retry.

Use this to remove one Python version and every environment using it:

# Optional preview
scuv list --python-version 3.12

# Remove Python 3.12 and all dependent environments
scuv uninstall 3.12 --cascade

# Verify cleanup
scuv list --pythons
scuv doctor

For CI/scripts, add --force to skip confirmation.

Use this to inspect what scuv currently manages:

# All managed Python versions
scuv list --pythons

# All environments and their Python versions
scuv list

# Environments associated with one Python version
scuv list --python-version 3.12

For scripts, use --json or --bare.

If the required version is not available from default scuv/uv sources:

# Recommended: explicit interpreter path
scuv create myenv --python-path /opt/python-debug/bin/python3

# Alternative: PATH-based discovery
export PATH="/opt/python-debug/bin:$PATH"
scuv create myenv 3.13

Verify integration with uv python list, scuv info myenv, and scuv doctor -v.

Need temporary or directory-specific behavior without touching global settings?

# Temporary: current shell only
export SCUV_NO_AUTO=1
unset SCUV_NO_AUTO

# Directory-local behavior (writes .scuv-version in current directory)
scuv use system      # force system Python for this project
scuv use myproject   # pin this project to a specific env

# Terminal-only override (no file changes)
scuv shell system
scuv shell --unset

Minimum supported uv is 0.5.14. Run scuv doctor to verify your installation.

cargo install scoop-uv  # installs the scuv command

# Add to ~/.zshrc or ~/.bashrc
export PATH="$HOME/.cargo/bin:$PATH"

The CLI command was renamed in v0.15.0 (scoop → scuv). One-time migration:

# 1. Update — installs the new `scuv` binary
scoop self update        # or: cargo install scoop-uv
# ("could not locate the freshly installed `scoop` binary" warning is
#  expected across the rename — the update itself already succeeded)

# 2. Remove the old binary if cargo left one behind
rm -f ~/.cargo/bin/scoop

# 3. Update your shell rc: scoop init → scuv init
#    ~/.zshrc / ~/.bashrc:  eval "$(scuv init zsh)"      # or bash
#    fish:                  scuv init fish | source

# 4. Move your freezer
mv ~/.scoop ~/.scuv

# 5. Restart your shell, then verify
scuv doctor              # flags anything left over

Legacy SCOOP_* env vars and .scoop-version / .scoop.toml files keep working (with a one-shot deprecation warning) until v0.16.0, and typing scoop in bash/zsh/fish still works through a deprecated forwarder that warns and calls scuv. Skipping step 2 is the one dangerous gap: a leftover old binary keeps running 0.14.x silently, without any warning.

Zsh (macOS default):

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 (Core or Windows PowerShell):

Add-Content $PROFILE 'Invoke-Expression (& scuv init powershell)'
. $PROFILE

scuv --version
# → scuv 0.15.0 🍨

• ✅ Auto-activation — enter a directory with .scuv-version, environment activates
• ✅ Tab completion — commands, environments, Python versions
• ✅ Shell wrapper — scuv activate/deactivate works correctly
• ✅ Migration ready — import from pyenv, conda, virtualenvwrapper
• ✅ Multi-language — English, 한국어, 日本語, Português (BR)

Add scuv after pyenv in your rc file (order matters — scuv gets the last scoop! 🍨):

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

# Example: disable auto-activation
echo 'export SCUV_NO_AUTO=1' >> ~/.zshrc

Your ice cream parlor lives here:

~/.scuv/                    # 🧊 The Freezer
├── virtualenvs/             # 🍨 All your flavors
│   ├── myproject/           #    → Python 3.12 flavor
│   ├── webapp/              #    → Python 3.11 flavor
│   └── experiment/          #    → Python 3.13 flavor
└── version                  # 🥄 Default scuv preference

Version file priority (first match wins):

SCUV_VERSION (env)  →  "Override for this shell session" (set by scuv shell)
.scuv-version       →  "I want THIS flavor here" (local + parent walk)
~/.scuv/version     →  "My usual order" (global default)

Note: .python-version is not supported. Use .scuv-version for version pinning.

Tip: Most commands support --json for machine-readable output.

For the complete command reference, see Commands Documentation →

📖 Read the Full Documentation →

Current MSRV: 1.88 (required by Rust Edition 2024)

scuv follows an N-1 MSRV policy — we support the current stable Rust and one previous version (~6 week lag).

src/
├── cli/           # 🎮 Command parsing (clap)
│   └── commands/  # Individual command handlers
├── core/          # 🧠 Domain logic
│   ├── version    # Version file resolution
│   ├── metadata   # Virtualenv metadata (JSON)
│   ├── virtualenv # Virtualenv entity
│   ├── doctor     # Health diagnostics
│   └── migrate/   # Migration (pyenv, conda, venvwrapper)
├── shell/         # 🐚 Shell integration (bash, zsh, fish, powershell)
├── uv/            # ⚡ uv CLI wrapper
├── output/        # 🎨 Terminal UI & JSON output
├── i18n.rs        # 🌏 Internationalization (en, ko, ja, pt-BR)
├── config.rs      # ⚙️ User configuration
└── error, paths, validate  # Utilities

Licensed under either of:

• MIT License
• Apache License, Version 2.0

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work shall be dual licensed as above, without any additional terms or conditions.

If you find this project useful, consider buying me a coffee (or an ice cream 🍨)!

Thanks goes to these wonderful people (emoji key):

azamarassy 🌍

Murillo Bazilio 🌍

Tosinibikunle 📖

This project stands on the shoulders of giants:

• uv by Astral — The blazing-fast Python package manager that powers scuv's backend. Without uv's incredible speed and reliability, scuv wouldn't exist. Thank you to Charlie Marsh and the entire Astral team for revolutionizing Python tooling.

• pyenv & pyenv-virtualenv — The original inspiration for scuv's workflow. pyenv taught us how Python version management should feel, and pyenv-virtualenv showed us how to centralize virtual environments elegantly.

• virtualenv by PyPA — The pioneer of Python virtual environments. Thank you to Ian Bicking for the original concept that changed how we isolate Python projects.

• Python — The language that made programming accessible to everyone. scuv exists to make Python development even more delightful. Thank you to Guido van Rossum and the Python community.

• Rust — The language that makes scuv fast, safe, and reliable. Thank you to the Rust team and Ferris 🦀 for proving that systems programming can be both powerful and enjoyable.

I built scuv because I needed it — and now it's yours too. 🍨

Grab a scoop, enjoy the flavor, and if you have thoughts to share, the door to the ice cream parlor is always open.

Issues · Discussions · PRs Welcome