Skip to main content

Toolchain

Installation​

scoop install main/uv
echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc
echo 'eval "$(uvx --generate-shell-completion bash)"' >> ~/.bashrc
uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"
rm ~/.local/bin/uv ~/.local/bin/uvx

Mirrors​

# Python mirror
export UV_PYTHON_INSTALL_MIRROR="https://gh-proxy.com/github.com/indygreg/python-build-standalone/releases/download"
# PyPI mirror
export UV_DEFAULT_INDEX="https://mirrors.aliyun.com/pypi/simple"

Python​

Install Python:

uv python install --default # Global
uv python install 3.14      # Virtual environment
uv python list
uv run --python 3.14 script.py
uvx python@3.14 -c "print('hello world')"

Initialization​

uv init hello-app
uv init --package hello-package
uv init --lib hello-lib
uv init --script hello-script.py --python 3.14

Dependencies​

Manage dependencies:

uv add 'requests==2.31.0' # 增加依赖
uv add -r requirements.txt # Import from requirements files
uv lock --upgrade-package requests # 更新项目依赖
uv remove requests # 删除项目依赖

uv sync
uv tree --outdated
uv tree --depth 2
uv run main.py
Distribution and Import

Python 中存在两个不同的包名：

概念英文术语示例用途
分发包名Distribution Packagepython-dotenvuv add xxx
导入包名Import Packagedotenvfrom xxx import ...

安装包后, site-packages 目录会包含两类文件夹:

  • *.dist-info/ 目录名对应 PyPI 包名
  • 源码目录名对应导入名
  • top_level.txt 文件记录了导入名映射
# 查看包安装位置和版本
uv pip show python-dotenv

# 查看依赖树
uv tree

Lockfile​

Create lockfile:

uv lock

Virtual Environment​

Manage virtual environments:

# 创建并激活虚拟环境
uv venv
source .venv/bin/activate

# 退出虚拟环境
deactivate

# 强制安装基础包（如 pip, setuptools, wheel）
uv venv --seed

Scripts​

Run standalone scripts:

uv init --script example.py --python 3.14
uv add --index "https://mirrors.aliyun.com/pypi/simple" --script example.py 'requests<3' 'rich'
uv run example.py
uv run --python 3.14 example.py

Tools​

Execution​

uv tool install black
uv tool run black ./myfile.py

uvx pycowsay 'hello world!'
uvx python@3.14.2 -c "print('hello world')"

Development​

Hot reload:

uv tool install --editable packages/agent-cli

Project​

[project]
name = "project"
version = "0.1.0"
requires-python = ">=3.12.0"
dependencies = [ "torch>=2.6.0" ]

[tool.uv.sources]
torch = [
  { index = "pytorch-cpu", marker = "sys_platform != 'linux'" },
  { index = "pytorch-cu124", marker = "sys_platform == 'linux'" },
]

[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
explicit = true

[[tool.uv.index]]
name = "pytorch-cu124"
url = "https://mirror.sjtu.edu.cn/pytorch-wheels/cu124"
explicit = true

Workspace​

Monorepo​

[project]
name = "albatross"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
  "bird-feeder",
  "tqdm>=4,<5",
]

[tool.uv.sources]
bird-feeder = { workspace = true }

[tool.uv.workspace]
members = [ "packages/*" ]
exclude = [ "packages/seeds" ]
albatross
├── packages
│   ├── bird-feeder
│   │   ├── pyproject.toml
│   │   └── src
│   │       └── bird_feeder
│   │           ├── __init__.py
│   │           └── foo.py
│   └── seeds
│       ├── pyproject.toml
│       └── src
│           └── seeds
│               ├── __init__.py
│               └── bar.py
├── pyproject.toml
├── README.md
├── uv.lock
└── src
    └── albatross
        └── main.py

Package​

# Initialize package
uv init --package packages/bash-agent

# Add workspace package as dependency
uv add --workspace bash-agent

# Run package
uv run bash-agent
[project]
name = "bash-agent"
version = "0.1.0"
description = "Minimal Claude Code."
readme = "README.md"
requires-python = ">=3.14"

[project.scripts]
bash-agent = "bash_agent:main"

[build-system]
requires = [ "uv_build>=0.9.27,<0.10.0" ]
build-backend = "uv_build"

Command​

uv add --package bash-agent anthropic python-dotenv

Caching​

uv cache dir
uv cache clean
uv cache prune

Dockerfile​

FROM python:3.12-slim-bookworm
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
ENV UV_SYSTEM_PYTHON=1

# Copy the project into the image
ADD . /app

WORKDIR /app

# Install dependencies
RUN uv sync --locked

# Install requirements
COPY requirements.txt .
RUN uv pip install -r requirements.txt

CMD ["uv", "run", "my_app"]

Linter​

uv add --dev pyright ruff
[tool.pyright]
typeCheckingMode = "strict"
include = [ "packages" ]
extraPaths = [ "packages/agent-cli/src" ]

[tool.ruff.lint]
select = [
  "E", # pycodestyle
  "F", # Pyflakes
  "UP", # pyupgrade
  "B", # flake8-bugbear
  "SIM", # flake8-simplify
  "I", # isort
]
ignore = [ "E501" ] # 忽略行长度限制
uvx ruff check
uvx ruff format ./script.py

Library​

ASGI​

HTTP​

UI​

  • Rich: Rich text and beautiful formatting for terminal.
  • Textual: Build sophisticated user interfaces.
  • Progress: Fast, Extensible Progress Bar for CLI.
  • IPython: Productive interactive computing.
  • Art: ASCII art.

AI​

  • Extract: Extracting structured information from unstructured text using LLMs.
  • Toad: Unified client for terminal agents.

Debugging​

Testing​