YouTip

## Python3.x uv Introduction Tutorial -- Python Package and Environment Management Tool In Python development, package management and environment isolation are issues every developer encounters. Whether it's the slowness of pip, the cumbersome nature of virtualenv, or the bloat of conda, uv has given developers hope for a more efficient solution. ### What is uv? uv is a Python package manager and environment manager written in Rust, developed by Astral. Its primary goal is to deliver performance 10–100 times faster than existing tools while maintaining a simple and intuitive user experience. uv can replace tools like pip, virtualenv, pip-tools, and pyenv, offering one-stop services such as dependency management, virtual environment creation, and Python version control. ### Advantages of uv * **Extremely Fast:** Written in Rust, uv outperforms pip and other package managers, speeding up dependency installation by 10–100 times. * **Integrated Features:** Combines dependency resolution, package installation, environment management, and Python version control into a single tool, eliminating the need to install and learn multiple utilities. * **Deterministic Builds:** uv generates a `uv.lock` file, ensuring that identical dependency versions are installed across all environments, avoiding the "works on my machine" problem. * **Compatibility with Existing Tools:** uv can handle `requirements.txt` and `pyproject.toml`, seamlessly replacing pip in your current workflow. * * * ### Installing on macOS We recommend using Homebrew: ```bash brew install uv Alternatively, use the official installation script: ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ### Installing on Linux ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ### Installing on Windows Use Winget: ```bash winget install uv Or use the official PowerShell installation script: ```powershell irm https://astral.sh/uv/install.ps1 | iex After installation, verify success: ```bash uv --version The output should resemble this: uv 0.8.14 (Homebrew 2025-08-28) * * * ## 1. Managing Python Versions uv includes built-in Python version management, so there's no need to install additional tools like pyenv. List available Python versions: ```bash uv python list Output example: cpython-3.14.0rc2-macos-aarch64-none cpython-3.13.7-macos-aarch64-none cpython-3.12.11-macos-aarch64-none cpython-3.11.13-macos-aarch64-none cpython-3.10.18-macos-aarch64-none cpython-3.9.6-macos-aarch64-none pypy-3.11.13-macos-aarch64-none Install a specific Python version: ```bash # Install the latest Python 3.12 uv python install 3.12 # Install a specific version uv python install 3.11.6 # Install PyPy uv python install pypy3.10 Set the global default Python version: ```bash uv python default 3.12 Fix the Python version for the current project (creates a `.python-version` file): ```bash uv python pin 3.12 After running this command, a `.python-version` file will be created in the current project directory. Open it to see the version number: 3.12 * * * ## 2. Managing Virtual Environments Create a virtual environment: ```bash # Create a virtual environment named .venv in the current directory (using the system's default Python) uv venv # Create a virtual environment using a specified Python version uv venv --python 3.12 Activate the virtual environment: ```bash # macOS / Linux source .venv/bin/activate # Windows (PowerShell) .venvScriptsactivate Deactivate the virtual environment: ```bash deactivate > In daily development, you can use `uv run` to directly execute scripts without manually activating the virtual environment. * * * ## 3. Package Management (pip-Compatible Mode) uv provides a fully pip-compatible command interface, allowing you to replace pip commands in your existing workflows: Install a package: ```bash # Install the latest version uv pip install requests # Install a specific version uv pip install requests==2.31.0 # Install from requirements.txt uv pip install -r requirements.txt Upgrade a package: ```bash uv pip install --upgrade requests Uninstall a package: ```bash uv pip uninstall requests List installed packages: ```bash uv pip list Export dependencies from the current environment to `requirements.txt`: ```bash uv pip freeze > requirements.txt * * * ## 4. Project Management (Recommended Method) uv supports modern project management centered around `pyproject.toml`, which is the recommended approach over pip-based workflows—especially for team collaboration and multi-environment deployments. ### Initialize a Project ```bash uv init my_project cd my_project This creates the following basic project structure: my_project/ ├── pyproject.toml # Project configuration and dependency declarations ├── .python-version # Fixed Python version ├── README.md └── main.py ### Adding and Removing Dependencies In project mode, we recommend using `uv add` and `uv remove` to manage dependencies. These commands automatically update both `pyproject.toml` and `uv.lock`: ```bash # Add production dependencies uv add requests # Add a specific version uv add "requests>=2.31.0" # Add development dependencies (used only in development environments, such as testing frameworks) uv add --dev pytest ruff # Remove a dependency uv remove requests ### Syncing All Project Dependencies (uv sync) After cloning a project or updating `pyproject.toml`, run the following command to install all dependencies at once: ```bash uv sync > **Note on `uv sync`:** Similar to `pip install -r requirements.txt`, it installs all dependencies based on `pyproject.toml` and `uv.lock`, ensuring consistency across environments. If installation is slow, you can configure a domestic mirror source in `pyproject.toml`: ```toml [tool.uv] index-url = "https://pypi.tuna.tsinghua.edu.cn/simple" ### Generating/Updating the Lock File ```bash uv lock This command parses the dependencies listed in `pyproject.toml` and generates (or updates) the `uv.lock` file. The `uv.lock` file should be committed to version control to ensure that all team members use identical dependency versions. * * * ## 5. Running Scripts (uv run) `uv run` is an extremely useful command in uv. It allows you to run scripts or commands directly without manually activating a virtual environment. uv automatically locates and uses the correct environment: ```bash # Run a Python script directly uv run main.py # Run tests in the project uv run pytest # Execute any command (within the context of the virtual environment) uv run python -c "import requests; print(requests.__version__)" Using `uv run` instead of manually activating the environment offers advantages: it prevents accidentally using the wrong Python version and avoids forgetting to activate the environment, making it especially suitable for CI/CD pipelines and automated scripting. * * * ## Migrating to uv If you're currently using other tools, here's how to migrate to uv: **From pip + virtualenv:** ```bash # Create and activate a virtual environment uv venv source .venv/bin/activate # Install existing dependencies uv pip install -r requirements.txt **From pip-tools:** ```bash # Compile dependencies (replace pip-compile) uv pip compile requirements.in -o requirements.txt # Sync the environment (replace pip-sync) uv pip sync requirements.txt **From poetry or pdm:** ```bash # Use the existing pyproject.toml directly uv sync