uv命令
######

* GitHub: https://github.com/astral-sh/uv
* 文档: https://docs.astral.sh/uv/


.. note:: 🚀 A single tool to replace pip, pip-tools, pipx, poetry, pyenv, virtualenv, and more.


* An extremely fast Python package and project manager, written in Rust.


常用操作
========

uv 替换 pip（Python 包管理）::

    uv pip install requests
    uv pip install -r requirements.txt
    uv pip uninstall requests


uv 替换 pip-tools（依赖锁定 & 解析）::

    # 解析 pyproject.toml 并生成 requirements.txt
    uv pip compile pyproject.toml --output-file requirements.txt

uv 替换 pipx（安装全局 CLI 工具）::

    # 全局安装 CLI 工具
    uv venv install httpx
    # 运行 black（无需全局安装）
    uv venv run black --version

uv 替换 poetry（项目依赖管理）::

    # 初始化项目(生成新项目，里面有文件pyproject.toml)
    uv init <proj>
    # 读取 pyproject.toml 文件中的 [tool.uv.dependencies] 部分，自动安装列出的依赖库
    uv pip install
    # 依赖添加到你的 pyproject.toml 文件中并安装
    uv add uvicorn
    # 安装项目依赖(基于uv.lock)，如果没有.venv会创建
    uv sync
    uv sync --index-url https://mirrors.aliyun.com/pypi/simple/


uv 替换 virtualenv（虚拟环境管理）::

    # 创建一个新的 Python 虚拟环境（类似 python -m venv）
    # 说明：不指定<path>时，<path>=.venv
    uv venv <path>



.. warning:: ⚠️ uv 不能直接替代 pyenv，但可以配合 pyenv 使用。


Project management
==================

* uv manages project dependencies and environments, with support for lockfiles, workspaces, and more, similar to ``rye`` or ``poetry``::

    $ uv init example
    Initialized project `example` at `/home/user/example`

    $ cd example

    $ uv add ruff
    Creating virtual environment at: .venv
    Resolved 2 packages in 170ms
       Built example @ file:///home/user/example
    Prepared 2 packages in 627ms
    Installed 2 packages in 1ms
     + example==0.1.0 (from file:///home/user/example)
     + ruff==0.5.4

    $ uv run ruff check
    All checks passed!



Tool management
===============

* uv executes and installs command-line tools provided by Python packages, similar to ``pipx``.
* Run a tool in an ephemeral environment using uvx (an alias for uv tool run)::

    $ uvx pycowsay 'hello world!'
    Resolved 1 package in 167ms
    Installed 1 package in 9ms
     + pycowsay==0.0.0.2
      """

      ------------
    < hello world! >
      ------------
       \   ^__^
        \  (oo)\_______
           (__)\       )\/\
               ||----w |
               ||     ||


Install a tool with uv tool install::

    $ uv tool install ruff
    Resolved 1 package in 6ms
    Installed 1 package in 2ms
     + ruff==0.5.4
    Installed 1 executable: ruff

    $ ruff --version
    ruff 0.5.4



Python management
=================

* uv installs Python and allows quickly switching between versions.
* Install multiple Python versions::

    $ uv python install 3.10 3.11 3.12
    Searching for Python versions matching: Python 3.10
    Searching for Python versions matching: Python 3.11
    Searching for Python versions matching: Python 3.12
    Installed 3 versions in 3.42s
     + cpython-3.10.14-macos-aarch64-none
     + cpython-3.11.9-macos-aarch64-none
     + cpython-3.12.4-macos-aarch64-none


Download Python versions as needed::

    $ uv venv --python 3.12.0
    Using Python 3.12.0
    Creating virtual environment at: .venv
    Activate with: source .venv/bin/activate

    $ uv run --python pypy@3.8 -- python --version
    Python 3.8.16 (a9dbdca6fc3286b0addd2240f11d97d8e8de187a, Dec 29 2022, 11:45:30)
    [PyPy 7.3.11 with GCC Apple LLVM 13.1.6 (clang-1316.0.21.2.5)] on darwin
    Type "help", "copyright", "credits" or "license" for more information.
    >>>>

Use a specific Python version in the current directory::

    $ uv python pin pypy@3.11
    Pinned `.python-version` to `pypy@3.11`


Script support
==============

* uv manages dependencies and environments for single-file scripts.
* Create a new script and add inline metadata declaring its dependencies::

    $ echo 'import requests; print(requests.get("https://astral.sh"))' > example.py

    $ uv add --script example.py requests
    Updated `example.py`

    $ cat example.py
    # /// script
    # requires-python = ">=3.12"
    # dependencies = [
    #     "requests",
    # ]
    # ///
    import requests; print(requests.get("https://astral.sh"))

Then, run the script in an isolated virtual environment::

    $ uv run example.py
    Reading inline script metadata from: example.py
    Installed 5 packages in 12ms
    <Response [200]>


A pip-compatible interface
==========================

* uv provides a drop-in replacement for common pip, pip-tools, and virtualenv commands.

Compile requirements into a platform-independent requirements file::

    $ uv pip compile docs/requirements.in \
       --universal \
       --output-file docs/requirements.txt
    Resolved 43 packages in 12ms


Create a virtual environment::

    $ uv venv
    Using Python 3.12.3
    Creating virtual environment at: .venv
    Activate with: source .venv/bin/activate


Install the locked requirements::

    $ uv pip sync docs/requirements.txt
    Resolved 43 packages in 11ms
    Installed 43 packages in 208ms
     + babel==2.15.0
     + black==24.4.2
     + certifi==2024.7.4
     ...