uv
# Boilerplate
uv init foo --project
cd foo/
source .venv/bin/activate
uv add --dev pytest
uv run pytest # or simply "pytest" since you're already in the venv
init
# Create project in a new dir
cd ~ # parent folder
uv init demo
uv init demo --project # create a src/ directory
# Create project in the current dir
mkdir demo
cd demo
uv init
sync
- What is does?
- Read your pyproject.toml
- Create/update the uv.lock file (if not there yet)
- Create a
.venv/ with dependencies from lock file (if not there yet)
- Install all dependencies
- It's similar to
npm i
uv sync
uv sync --extra dev # also install "project.optional-dependencies.dev"
uv sync --dev # same?
uv sync --reinstall # re-created .venv cleanly
uv lock
- What is does?
- Create/update the uv.lock file (if not there yet)
uv lock
uv lock --upgrade # upgrade dependencies respecting pyproject.toml
run
# Run the entrypoint of the project
uv run python main.py
uv run python main.py --arg1 value1
# Run python code
uv run python - <<'EOF'
import sys
sys.exit(1)
EOF
# Run python code interactively (and specify the version)
uv run --python [email protected] -- python
uv run --python 3.12.0 -- python
# Run an arbitrary command of a dependency
uv run ruff check
# Run a custom script
uv run start
# Run test deps
uv run pytest tests/
add
- Adds a dependency into
pyproject.toml and installs it in the virtual environment .venv/
- If there is no parent pyproject, it will fail
uv add "langchain"
uv add --dev pytest # adds to [dependency-groups].dev table
# Add a dependency for a single file
# Dependency are added as comments to the file
echo 'import requests; print(requests.get("http://example.com"))' > demo.py
uv add requests --script demo.py
# Run it
uv run demo.py
uv python
- Install a python version for the current project
uv python install 3.10 3.11 3.12
uv python pin 3.11 # pin a version for the cwd
- Run tools in an ephemeral environment (similar to pipx, npx, etc)
# run
uv tool run pycowsay 'hello world!'
uvx pycowsay 'hello world!' # same
# --from defines which package to use
uvx --from mcpdoc \
mcpdoc \
--urls "LangGraph:https://langchain-ai.github.io/langgraph/llms.txt" "LangChain:https://python.langchain.com/llms.txt" \
--transport sse \
--port 8082 \
--host localhost
# installs a CLI tool globally (into ~/.local/bin), not into your project. It's like pipx install - it doesn't touch your pyproject.toml
# Each tool gets its own isolated virtual environment
uv tool install ruff # just install without running
uv tool install 'deepagents-cli[ollama,groq]'
uv venv
- Creates a virtual environment (like python -m venv)
- Does NOT install dependencies
- This command is not usually used. Prefer
uv sync instead
uv pip
- Mimic pip commands, it's a compatibility layer
- Pip is actually not used under the hood, it's just the same interface/commands
- This command is not usually used. Prefer
uv sync instead