--- title: "Getting Started with uv: Setting Up Your Python Project in 2026" description: "See how you can get started with uv, a next-generation Python package and project manager written in Rust by the Astral team." date: 2025-03-12 categories: ["vps"] tags: ["uv","python"] --- Python’s ecosystem has long been a powerhouse for developers, but managing dependencies, virtual environments, and Python versions has often felt clunky with traditional tools like `pip` and `venv`. Enter `uv`, a next-generation Python package and project manager written in Rust by the Astral team (known for the popular `ruff` linter). Launched in February 2024, `uv` has rapidly gained traction for its speed (10-100x faster than `pip`), seamless integration with existing workflows, and all-in-one approach to Python project management. In this article, we’ll walk through how to start using `uv` and set up a Python project from scratch, leveraging the latest features as of March 2026. ![wv speed image](@images/25/03/uv-speed.svg) ## What is uv? `uv` is an all-in-one Python tool designed to replace a patchwork of utilities like `pip` (package installer), `venv` (virtual environment manager), and even `poetry` (project manager). Built in Rust, it boasts performance that’s 10-100x faster than traditional tools, thanks to its optimized dependency resolver and aggressive caching strategy. It’s not just a package installer—it’s a full-fledged project manager that handles Python versions, virtual environments, dependencies, and script execution with ease. Key features of `uv` include: - **Speed**: Installs packages and resolves dependencies in seconds, not minutes. - **Unified Workflow**: Combines environment creation, package management, and script running into one tool. - **Standards Compliance**: Uses the standard `pyproject.toml` for configuration and a cross-platform `uv.lock` file for reproducible builds. - **No Manual Activation**: Automatically manages virtual environments without requiring you to activate them manually. As of March 2026, `uv` has matured significantly since its initial release, with stable support for project management, Python version handling, and seamless integration into existing workflows. Let’s see how to set it up. ## Setting Up Your Python Project with `uv` In this section we are going to set up a Python project using `uv`. We are going to install `uv` and create a new project. For seeing how you can easely deploy uv project on your VPS you can check our article [Deploying a Python uv Project with Git and Railpack in Dokploy](https://www.bitdoze.com/dokploy-python-railpack-uv/) ### Step 1: Installing uv To use `uv`, you first need to install it. Unlike many Python tools, `uv` doesn’t require a pre-existing Python installation because it can manage Python versions itself. However, it’s recommended to install it directly rather than via `pip` to avoid dependency conflicts with your system Python. Here’s how to install the latest version (as of March 2026, version 0.6.5 is available on PyPI, but always check [astral.sh](https://astral.sh) for updates): #### On macOS/Linux Open your terminal and run: ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` This downloads and installs `uv` as a standalone binary. Log: ```sh downloading uv 0.6.6 aarch64-apple-darwin no checksums to verify installing to /Users/user/.local/bin uv uvx everything's installed! To add $HOME/.local/bin to your PATH, either restart your shell or run: source $HOME/.local/bin/env (sh, bash, zsh) source $HOME/.local/bin/env.fish (fish) WARNING: The following commands are shadowed by other commands in your PATH: uv uvx ``` #### On Windows Using PowerShell: ```powershell irm https://astral.sh/uv/install.ps1 | iex ``` #### Verify Installation After installation, confirm it worked by checking the version: ```bash uv --version ``` You should see something like `uv 0.6.6`. If not, ensure `uv` is added to your system PATH (the installer usually handles this, but you might need to restart your terminal). Log: ```sh ╰─❯ uv --version uv 0.6.6 (c1a0bb85e 2026-03-12) ``` ### Step 2: Initializing a New Project With `uv` installed, let’s create a new Python project. `uv` makes this a breeze with the `uv init` command, which sets up a basic project structure. 1. **Create a Project Directory**: Navigate to where you want your project and run: ```bash uv init my-python-project cd my-python-project ``` This sets up a minimal project structure tailored for quick starts. As of March 2026, running `uv init` generates the following files and directories in your project root: ``` my-python-project/ ├── .python-version # Specifies the pinned Python version (e.g., "3.12") ├── main.py # A simple starter Python script ├── pyproject.toml # Project configuration file └── README.md # Basic project documentation (empty by default) ``` *Note:* Depending on your setup, you might also see hidden directories like `.git` (if you initialize a Git repository) or `.ropeproject` (if you're using an IDE like PyCharm with Rope for refactoring). These are not created by `uv` itself but may appear based on your environment or subsequent actions. The `pyproject.toml` file is the core of your project, following the PEP 621 standard. It looks something like this: ```toml [project] name = "my-python-project" version = "0.1.0" description = "Add your description here" readme = "README.md" requires-python = ">=3.13" dependencies = [] ``` The `main.py` file comes with a basic "Hello, World!" example: ```python def main(): print("Hello from my-python-project!") if __name__ == "__main__": main() ``` The `.python-version` file pins the Python version (e.g., `3.13`), and `README.md` starts as an empty file ready for your project description. 2. **Set a Python Version (Optional)** The `.python-version` file is created automatically by `uv init`, typically defaulting to the latest Python version available on your system (e.g., 3.12). To change it to a specific version: ```bash uv python pin 3.12 ``` This updates `.python-version` and ensures consistency across machines. Be sure to update the `requires-python = ">=3.12"` before in `pyproject.toml`. ### Step 3: Setting Up a Virtual Environment With traditional tools, you’d manually create a virtual environment using `python -m venv`. `uv` simplifies this with the `uv venv` command, automatically placing it in a `.venv` folder in your project root. Run: ```bash uv venv ``` You’ll see output like: ``` Using Python 3.12.7 Creating virtual environment at: .venv Activate with: source .venv/bin/activate ``` To activate it: - **macOS/Linux**: `source .venv/bin/activate` - **Windows**: `.venv\Scripts\activate` However, `uv` often eliminates the need to manually activate environments by handling this automatically with commands like `uv run` (more on that later). ### Step 4: Adding Dependencies Now, let’s add some packages to your project. `uv` manages dependencies via `pyproject.toml`, and you can add them interactively or manually. #### Interactive Method To add `requests` (a popular HTTP library): ```bash uv add requests ``` This updates `pyproject.toml` with: ```toml [project] dependencies = [ "requests>=2.32.3", ] ``` It also creates a `uv.lock` file, a cross-platform lockfile ensuring reproducible builds by pinning exact versions. #### Manual Method *Add the packages to `pyproject.toml`* Edit `pyproject.toml` directly. For example: ```toml [project] name = "my-python-project" version = "0.1.0" requires-python = ">=3.12" dependencies = [ "fastapi>=0.115.6", "pandas>=2.2.1", ] [dependency-groups] dev = ["pytest>=8.3.4"] ``` Here, `fastapi` and `pandas` are production dependencies, while `pytest` is a development dependency. **Installing Dependencies** To install all dependencies (including dev ones) into your virtual environment: ```bash uv sync ``` ```bash ❯ uv sync Resolved 25 packages in 1.37s Prepared 18 packages in 3.28s Installed 18 packages in 51ms + annotated-types==0.7.0 + anyio==4.8.0 + fastapi==0.115.11 + iniconfig==2.0.0 + numpy==2.2.3 + packaging==24.2 + pandas==2.2.3 + pluggy==1.5.0 + pydantic==2.10.6 + pydantic-core==2.27.2 + pytest==8.3.5 + python-dateutil==2.9.0.post0 + pytz==2025.1 + six==1.17.0 + sniffio==1.3.1 + starlette==0.46.1 + typing-extensions==4.12.2 + tzdata==2025.1 ``` This reads `pyproject.toml`, resolves dependencies, and installs them into `.venv`. If you only want production dependencies, use: ```bash uv sync --no-dev ``` The speed of `uv sync` is remarkable—often completing in milliseconds compared to minutes with `pip`. ### Step 5: Writing and Running Code Let’s create a simple script. In `my_python_project/main.py`, add: ```python import requests def fetch_data(): response = requests.get("https://api.github.com") print(response.json()) if __name__ == "__main__": fetch_data() ``` To run it, use: ```bash uv run python main.py ``` `uv run` ensures the script runs in the project's virtual environment, installing dependencies if needed. You can also run it directly: ```bash uv run main.py ``` Want to learn more about running standalone scripts with uv without creating full projects? Check out our comprehensive guide on [Running Test Scripts with uv: No Dependencies Management Required](https://www.bitdoze.com/uv-run-scripts-guide/) for advanced script execution techniques. ### Step 6: Managing Your Project As your project grows, `uv` offers tools to keep it organized. - **Update Dependencies** To upgrade packages to their latest compatible versions: ```bash uv sync --upgrade ``` - **Export to requirements.txt** If you need a traditional `requirements.txt`: ```bash uv export --format requirements-txt > requirements.txt ``` - **Run Commands** Execute any command in the project environment: ```bash uv run pytest ``` ### Step 7: Managing Python Versions List installed Python versions: ```bash uv python list ``` Install a specific version: ```bash uv python install 3.11 ``` ### Step 8: Removing Packages with uv As your project evolves, you might need to remove a package that’s no longer needed. With `uv`, uninstalling dependencies is just as straightforward as adding them, and it keeps your project configuration and environment in sync. 1. **Remove a Package** Suppose you added `requests` earlier but no longer need it. To remove it: ```bash uv remove requests ``` This command: - Deletes `requests` from the `[project.dependencies]` section in your `pyproject.toml`. - Uninstalls the package from the virtual environment (`.venv`). - Updates the `uv.lock` file to reflect the change, ensuring reproducibility. For example, if your `pyproject.toml` originally had: ```toml [project] name = "my-python-project" version = "0.1.0" description = "A new Python project" requires-python = ">=3.12" dependencies = [ "requests>=2.31.0", ] ``` After running `uv remove requests`, it becomes: ```toml [project] name = "my-python-project" version = "0.1.0" description = "A new Python project" requires-python = ">=3.12" dependencies = [] ``` 2. **Remove a Development Dependency** If you installed a development dependency like `pytest` with `uv add --dev pytest` and want to remove it: ```bash uv remove --dev pytest ``` This targets the `[dependency-groups.dev]` section in `pyproject.toml` and removes `pytest` from both the configuration and the virtual environment. 3. **Sync the Environment (Optional)** While `uv remove` typically updates the environment automatically, you can ensure everything is consistent by running: ```bash uv sync ``` This reconciles the virtual environment with the updated `pyproject.toml` and `uv.lock`, removing any orphaned packages. 4. **Manual Removal (Not Recommended)** If you manually edit `pyproject.toml` to remove a dependency (e.g., deleting `requests` from the `dependencies` list), `uv` won’t automatically uninstall it from `.venv` until you run `uv sync`. Stick to `uv remove` to avoid this extra step and keep your project clean. ## Why Choose uv in 2026? By March 2026, `uv` has solidified its place as a game-changer in Python development. Its speed alone—often installing dependencies 10-20x faster than `pip`—is a compelling reason to switch. Add to that its seamless integration with modern standards (`pyproject.toml`, `uv.lock`), automatic Python version management, and a streamlined workflow, and it’s clear why developers, including the FastAPI team, have adopted it. For beginners, `uv` reduces the complexity of managing Python environments. For pros, it saves time and ensures reproducibility. Whether you’re building a small script or a large application, `uv` adapts to your needs. ## What's Next? Now that you've mastered the basics of uv project management, you might want to explore more advanced capabilities: - **Script Execution**: Learn how to run standalone Python scripts without creating full projects in our guide [Running Test Scripts with uv: No Dependencies Management Required](https://www.bitdoze.com/uv-run-scripts-guide/) - **Text-to-Speech**: Build a powerful audio generation script with [Text-to-Speech with uv: Create Audio from Text in Python](https://www.bitdoze.com/uv-text-to-speech-script/) - **Deployment**: See how to deploy uv projects in our article [Deploying a Python uv Project with Git and Railpack in Dokploy](https://www.bitdoze.com/dokploy-python-railpack-uv/) ## Conclusion `uv` is a game-changer for Python developers in 2025, offering a fast, unified, and intuitive way to manage projects. From installation to dependency management, it reduces friction and lets you focus on coding. To stay updated, check the official documentation at [docs.astral.sh/uv](https://docs.astral.sh/uv) or the GitHub repo at [github.com/astral-sh/uv](https://github.com/astral-sh/uv). Ready to try it? Install `uv`, initialize a project, and experience Python development at warp speed. Happy coding!