🍨 scoop

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

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

🍨 More badges

What is scoop? 🍨

scoop 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 (~/.scoop/) keeps all your flavors fresh
• Flavors are your virtualenvs — mix once, serve anywhere
• One scoop is all you need to get the right env

60-Second Quick Start ⚡

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

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

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

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

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

Set Python 3.11.0 as Global Default

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

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

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

Create a Project Env with Python 3.9.5

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

scoop install 3.9.5
scoop create myproject 3.9.5
scoop info myproject

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

Uninstall Python + Associated Envs

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

# Optional preview
scoop list --python-version 3.12

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

# Verify cleanup
scoop list --pythons
scoop doctor

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

List Python Versions + Associated Envs

Use this to inspect what scoop currently manages:

# All managed Python versions
scoop list --pythons

# All environments and their Python versions
scoop list

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

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

Integrate Custom or Pre-Existing Python

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

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

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

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

Project-Scoped Auto-Activation Control

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

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

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

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

Installation 🍨

Prerequisites

Install scoop

cargo install scoop-uv

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

Shell Setup

Step 1: Add to your shell config

Zsh (macOS default):

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

Bash:

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

Fish:

echo 'eval (scoop init fish)' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

PowerShell (Core or Windows PowerShell):

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

Step 2: Verify

scoop --version
# → scoop 0.8.0 🍨

What this enables

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

Using with pyenv

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

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

Options

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

The Freezer 🧊

Your ice cream parlor lives here:

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

Version file priority (first match wins):

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

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

Commands 🍨

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

Essential Commands

For the complete command reference, see Commands Documentation →

Documentation 📚

📖 Read the Full Documentation →

Minimum Supported Rust Version (MSRV) 🦀

Current MSRV: 1.85 (required by Rust Edition 2024)

scoop 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

License

Licensed under either of:

• MIT License
• Apache License, Version 2.0

at your option.

Contribution

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.

Support 🍨

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

Contributors ✨

Thanks goes to these wonderful people (emoji key):

azamarassy 🌍

Murillo Bazilio 🌍

Tosinibikunle 📖

Acknowledgments 🍨

This project stands on the shoulders of giants:

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

• pyenv & pyenv-virtualenv — The original inspiration for scoop'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. scoop exists to make Python development even more delightful. Thank you to Guido van Rossum and the Python community.

• Rust — The language that makes scoop 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 scoop 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