Readme
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
The Old Way (Yuck ๐ซ )
The scoop Way (Fresh ๐จ)
. venv scattered across projects
~/.scoop/virtualenvs/ centralized
Manual source . venv/ bin/ activate
Auto-activate on directory entry
pyenv-virtualenv is slow
uv-powered, 100x+ faster
Which Python? Which venv? Chaos.
scoop doctor checks everything
Migrating envs? Manual nightmare.
scoop migrate - - all does it all
English-only CLI
Multi-language support (en, ko)
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 โ " I want THIS flavor here"
. python- version โ " pyenv compatibility mode"
~ / . scoop/ version โ " My usual order"
Installation ๐จ
Prerequisites
Dependency
Install
Why
uv
curl - LsSf https://astral.sh/uv/install.sh | sh
The secret ingredient ๐ฎ
Rust
curl -- proto ' =https' -- tlsv1 .2 - sSf https://sh.rustup.rs | sh
Build from source
Install scoop
cargo install scoop-uv
๐ก scoop: command not found ?
Cargo installs binaries to ~/.cargo/bin . Ensure it's in your PATH:
# Add to ~/.zshrc or ~/.bashrc
export PATH="$HOME/.cargo/bin:$PATH"
Or restart your terminal after installing Rust.
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
Step 2: Verify
scoop -- version
# โ scoop 0.3.1 ๐จ
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 โ Korean (ko) and English (en) supported
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
Variable
Effect
SCOOP_NO_AUTO = 1
Disable auto-activation
SCOOP_HOME = / path
Custom freezer location (default: ~/.scoop )
# Example: disable auto-activation
echo 'export SCOOP_NO_AUTO=1' >> ~/.zshrc
Quick Start ๐จ
# Stock up the freezer ๐ง
scoop install 3.12
# Mix a new flavor ๐ฆ
scoop create myproject 3.12
# Pick your flavor for this directory (auto-activates!)
scoop use myproject
(myproject) $ pip install requests
# Check what's in the freezer
scoop list # List all flavors
scoop list --pythons # List Python versions
scoop list --json # For the data nerds ๐ค
# Clean up
scoop remove myproject # Melt it away ๐ง
Commands ๐จ
Tip: All commands support --json for machine-readable output.
Everyday Scooping
Command
Description
scoop create < name> [ version]
Mix a new flavor (default: latest Python)
scoop use < name>
Pick your flavor (auto-activates)
scoop use < name> - - link
Also create . venv symlink for IDE
scoop use < name> - - global
Set as your usual order
scoop list
What's in the freezer?
scoop list - - pythons
What Python versions do we have?
scoop list - - json
Output as JSON
scoop info < name>
Show detailed info about a flavor
scoop info < name> - - json
Output info as JSON
scoop remove < name>
Melt a flavor away
Managing the Freezer
Command
Description
scoop install [ version]
Stock up on Python (default: latest)
scoop install - - stable
Get the oldest supported Python (3.10)
scoop uninstall < version>
Remove a Python version
Health Check ๐ฉบ
Command
Description
scoop doctor
Is everything fresh? Check your setup!
scoop doctor - - fix
Auto-fix issues where possible
scoop doctor - - json
Output diagnostics as JSON
Migration ๐
Command
Description
scoop migrate list
Show environments to migrate
scoop migrate @ < name>
Migrate a single environment
scoop migrate - - all
Migrate all environments
Supported sources: pyenv-virtualenv, virtualenvwrapper, conda
Language ๐
Command
Description
scoop lang
Show current language
scoop lang < code>
Set language (en, ko)
scoop lang - - list
List supported languages
scoop lang - - reset
Reset to system default
Shell Integration
Command
Description
scoop init < shell>
Output shell initialization script
scoop completions < shell>
Generate completion script
Shells supported: bash , zsh , fish , powershell
For complete command reference, see docs/commands.md .
Architecture ๐๏ธ
Built with Rust for speed and reliability:
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)
โโโ uv/ # โก uv CLI wrapper
โโโ output/ # ๐จ Terminal UI & JSON output
โโโ i18n. rs # ๐ Internationalization ( en, ko)
โโโ config. rs # โ๏ธ User configuration
โโโ error, paths, validate # Utilities
Design principle: The CLI outputs shell code to stdout, your shell evaluates it. Just like pyenv โ battle-tested pattern.
Documentation ๐จ
๐ Full Documentation
License
Licensed under either of:
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 ๐จ)!
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