JMARyA
c12fdfc9d5
All checks were successful
ci/woodpecker/push/validate_schema Pipeline was successful
238 lines
4.7 KiB
Markdown
238 lines
4.7 KiB
Markdown
---
|
||
obj: application
|
||
repo: https://github.com/astral-sh/uv
|
||
website: https://docs.astral.sh/uv
|
||
rev: 2025-06-05
|
||
---
|
||
|
||
# 🚀 `uv` – Python Package and Project Manager
|
||
`uv` is a high-performance Python package manager and project toolchain, written in Rust. It consolidates functionalities from multiple tools into a single, fast, and efficient interface, aiming to replace `pip`, `pipx`, `poetry`, `pyenv`, `virtualenv`, `pip-tools`, `twine`, and more.
|
||
|
||
## 🔧 Key Features
|
||
|
||
* **Unified Tooling:** Combines functionalities of multiple tools into one.
|
||
* **Blazing Fast:** 10–100x faster than `pip`.
|
||
* **Cross-Platform:** Supports macOS, Linux, and Windows.
|
||
* **Minimal Dependencies:** Single binary with no external dependencies.
|
||
* **Comprehensive Project Management:** Handles `pyproject.toml`, lockfiles, and more.
|
||
* **Python Version Management:** Install and manage multiple Python versions.
|
||
* **Tool Installation:** Install and run Python-based tools like `ruff`, `black`, etc.
|
||
* **Script Execution:** Run standalone Python scripts with inline dependencies.
|
||
|
||
## ⚙️ Usage
|
||
|
||
### Python Version Management
|
||
|
||
* **Install Python Versions:**
|
||
|
||
```bash
|
||
uv python install 3.10.7
|
||
```
|
||
|
||
* **List Installed Versions:**
|
||
|
||
```bash
|
||
uv python list
|
||
```
|
||
|
||
* **Pin Python Version for Project:**
|
||
|
||
```bash
|
||
uv python pin 3.10.7
|
||
```
|
||
|
||
* **Uninstall Python Version:**
|
||
|
||
```bash
|
||
uv python uninstall 3.10.7
|
||
```
|
||
|
||
### Virtual Environments
|
||
|
||
* **Create a Virtual Environment:**
|
||
|
||
```bash
|
||
uv venv
|
||
```
|
||
|
||
* **Create with Specific Python Version:**
|
||
|
||
```bash
|
||
uv venv --python 3.10
|
||
```
|
||
|
||
* **Activate the Environment:**
|
||
|
||
```bash
|
||
source .venv/bin/activate # macOS/Linux
|
||
.venv\Scripts\activate # Windows
|
||
```
|
||
|
||
* **Install Dependencies:**
|
||
|
||
```bash
|
||
uv pip install -r requirements.txt
|
||
```
|
||
|
||
* **Freeze Installed Packages:**
|
||
|
||
```bash
|
||
uv pip freeze > requirements.txt
|
||
```
|
||
|
||
### Project Management
|
||
|
||
* **Initialize a New Project:**
|
||
|
||
```bash
|
||
uv init my-project
|
||
```
|
||
|
||
* **Add a Dependency:**
|
||
|
||
```bash
|
||
uv add requests
|
||
```
|
||
|
||
* **Remove a Dependency:**
|
||
|
||
```bash
|
||
uv remove requests
|
||
```
|
||
|
||
* **Sync Dependencies:**
|
||
|
||
```bash
|
||
uv sync
|
||
```
|
||
|
||
* **Generate Lockfile:**
|
||
|
||
```bash
|
||
uv lock
|
||
```
|
||
|
||
* **Run Project Scripts:**
|
||
|
||
```bash
|
||
uv run script.py
|
||
```
|
||
|
||
* **Build Project:**
|
||
|
||
```bash
|
||
uv build
|
||
```
|
||
|
||
* **Publish Project:**
|
||
|
||
```bash
|
||
uv publish
|
||
```
|
||
|
||
### Tool Management
|
||
|
||
* **Install a Tool:**
|
||
|
||
```bash
|
||
uv tool install black
|
||
```
|
||
|
||
* **Uninstall a Tool:**
|
||
|
||
```bash
|
||
uv tool uninstall black
|
||
```
|
||
|
||
* **Run a Tool:**
|
||
|
||
```bash
|
||
uv tool run black .
|
||
```
|
||
|
||
* **List Installed Tools:**
|
||
|
||
```bash
|
||
uv tool list
|
||
```
|
||
|
||
|
||
### Running Python Scripts with Inline Dependencies
|
||
#### **Add Inline Metadata to Your Script**
|
||
To begin, you'll need to add metadata to your Python script to specify the required dependencies and Python version. This can be done using the `uv add --script` command:
|
||
|
||
```bash
|
||
uv add --script your_script.py 'requests' 'numpy'
|
||
```
|
||
|
||
This command will modify your script to include a special comment block at the top, indicating the dependencies:
|
||
|
||
```python
|
||
# /// script
|
||
# requires-python = ">=3.12"
|
||
# dependencies = [
|
||
# "requests",
|
||
# "numpy",
|
||
# ]
|
||
# ///
|
||
```
|
||
|
||
#### **Make the Script Executable**
|
||
To run your script directly from the command line, add a shebang line at the very top of your script:
|
||
|
||
```python
|
||
#!/usr/bin/env -S uv run --script
|
||
```
|
||
|
||
Ensure the script is executable:
|
||
|
||
```bash
|
||
chmod +x your_script.py
|
||
```
|
||
|
||
#### **Run the Script**
|
||
Now, you can execute your script directly:
|
||
```bash
|
||
./your_script.py
|
||
```
|
||
|
||
The first time you run it, `uv` will create an isolated virtual environment, install the specified dependencies, and execute the script. On subsequent runs, the environment is cached, leading to near-instant execution times .
|
||
|
||
## 📦 Compatibility with Existing Tools
|
||
`uv` is designed to be compatible with existing Python tools and workflows:
|
||
|
||
* **`pyproject.toml` Support:** Fully supports PEP 621-compliant `pyproject.toml` files.
|
||
* **`requirements.txt` Compatibility:** Works seamlessly with `requirements.txt` files.
|
||
* **`pip` Interface:** Provides a familiar `pip`-like interface for package management.
|
||
* **`pipx` Replacement:** Can install and run Python-based tools globally, replacing `pipx`.
|
||
* **`pyenv` Alternative:** Manages multiple Python versions without the need for `pyenv`.
|
||
|
||
## 🧪 Example
|
||
Here's a typical workflow using `uv`:
|
||
|
||
```bash
|
||
# Initialize a new project
|
||
uv init my-project
|
||
|
||
# Navigate into the project directory
|
||
cd my-project
|
||
|
||
# Create a virtual environment
|
||
uv venv
|
||
|
||
# Activate the environment
|
||
source .venv/bin/activate # macOS/Linux
|
||
.venv\Scripts\activate # Windows
|
||
|
||
# Add dependencies
|
||
uv add requests
|
||
|
||
# Generate lockfile
|
||
uv lock
|
||
|
||
# Install dependencies
|
||
uv sync
|
||
|
||
# Run the project script
|
||
uv run script.py
|
||
```
|