mirror of
https://github.com/astral-sh/uv.git
synced 2025-12-01 15:53:20 +00:00
f971631adf
Basically sick of dealing with mixed formatting here. Going with the
number at
7c08e61b73/.editorconfig (L20)
140 lines
4.2 KiB
Markdown
140 lines
4.2 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/activate
|
|
$ 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](../concepts/projects.md) documentation for more details about projects.
|