mirror of
https://github.com/astral-sh/uv.git
synced 2025-10-24 17:16:02 +00:00
145 lines
4.1 KiB
Markdown
145 lines
4.1 KiB
Markdown
# Working on projects
|
|
|
|
uv is capable of managing Python projects using a `pyproject.toml` with a `[project]` metadata table.
|
|
|
|
## Creating a new project
|
|
|
|
You can create a new Python project using the `uv init` command:
|
|
|
|
```console
|
|
$ uv init hello-world
|
|
$ cd hello-world
|
|
```
|
|
|
|
Alternatively, you can initialize a project in the working directory:
|
|
|
|
```console
|
|
$ mkdir hello-world
|
|
$ cd hello-world
|
|
$ uv init
|
|
```
|
|
|
|
This will create the following directory structure:
|
|
|
|
```text
|
|
.
|
|
├── pyproject.toml
|
|
├── README.md
|
|
└── src
|
|
└── hello-world
|
|
└── __init__.py
|
|
```
|
|
|
|
### Working on an existing project
|
|
|
|
If your project already contains a standard `pyproject.toml`, you can start
|
|
using uv without any extra work. Commands like `uv add` and `uv run` will
|
|
create a lockfile and virtual environment the first time they are used.
|
|
|
|
If you are migrating from an alternative Python package manager, you may need to
|
|
edit your `pyproject.toml` manually before using uv. uv uses a `[tool.uv]` section
|
|
in the `pyproject.toml` to support features that are not yet included in the `pyproject.toml` standard, such as development dependencies. Alternative Python package managers may use
|
|
different sections or format.
|
|
|
|
## Project structure
|
|
|
|
A project consists of a few important parts that work together and allow uv to
|
|
manage your project. Along with the files created by `uv init`, uv will create a
|
|
virtual environment and `uv.lock` file in the root of your project the first time you
|
|
run a project command.
|
|
|
|
### `pyproject.toml`
|
|
|
|
The `pyproject.toml` contains metadata about your project:
|
|
|
|
```toml title="pyproject.toml"
|
|
[project]
|
|
name = "hello-world"
|
|
version = "0.1.0"
|
|
description = "Add your description here"
|
|
readme = "README.md"
|
|
dependencies = []
|
|
|
|
[tool.uv]
|
|
dev-dependencies = []
|
|
```
|
|
|
|
This is where you specify dependencies, as well as details about the project
|
|
such as it's description or license. You can edit this file manually, or use
|
|
commands like `uv add` and `uv remove` to manage your project through the
|
|
CLI.
|
|
|
|
!!! tip
|
|
|
|
See the official [`pyproject.toml` guide](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) for more details on getting started with the `pyproject.toml` format.
|
|
|
|
### `.venv`
|
|
|
|
The `.venv` folder contains your project's virtual environment, a Python
|
|
environment that is isolated from the rest of your system. This is where uv will
|
|
install your project's dependencies.
|
|
|
|
### `uv.lock`
|
|
|
|
`uv.lock` is a cross-platform lockfile that contains exact information about your
|
|
project's dependencies. Unlike the `pyproject.toml` which is used to specify the
|
|
broad requirements of your project, the lockfile contains the exact resolved versions
|
|
that are installed in the virtual environment. This file should be checked into version
|
|
control, allowing for consistent and reproducible installations across machines.
|
|
|
|
`uv.lock` is a human-readable TOML file but is managed by uv and should not be
|
|
edited manually.
|
|
|
|
## Running commands
|
|
|
|
`uv run` can be used to run arbitrary scripts or commands in your project
|
|
environment. This ensures that the lockfile and virtual environment are
|
|
up-to-date before executing a given command:
|
|
|
|
```console
|
|
$ uv run python my_script.py
|
|
$ uv run flask run -p 3000
|
|
```
|
|
|
|
Alternatively, you can use `uv sync` to manually synchronize the lockfile and
|
|
virtual environment before executing a command:
|
|
|
|
```console
|
|
$ uv sync
|
|
$ source .venv/bin/active
|
|
$ python my_script.py
|
|
```
|
|
|
|
!!! note
|
|
|
|
The virtual environment must be active to run scripts and commands in the project without `uv run`. Virtual environment activation differs per shell and platform.
|
|
|
|
## Managing dependencies
|
|
|
|
You can add dependencies to your `pyproject.toml` with the `uv add` command.
|
|
This will also update the lockfile and virtual environment:
|
|
|
|
```console
|
|
$ uv add requests
|
|
```
|
|
|
|
You can also specify version constraints or alternative sources:
|
|
|
|
```console
|
|
# Specify a version constraint
|
|
$ uv add 'requests==2.31.0'
|
|
|
|
# Add a git dependency
|
|
$ uv add requests --git https://github.com/psf/requests
|
|
```
|
|
|
|
To remove a package, you can use `uv remove`:
|
|
|
|
```console
|
|
$ uv remove requests
|
|
```
|
|
|
|
## Next steps
|
|
|
|
See the [projects concept](../projects.md) documentation for more details about
|
|
projects.
|