db371560bc
To enforce the 100 character line limit in markdown files introduced in https://github.com/astral-sh/uv/pull/5635, and to automate the formatting of markdown files, i've added prettier and formatted our markdown files with it. I've excluded the changelog and the generated references documentation from this for having too many changes, but we can also include them. I'm not particular on which style we use. My main motivations are (major) not having to reflow markdown files myself anymore and (minor) consistence between all markdown files. I've chosen prettier for similar reason as we chose black, it's a single good style that's automated and shared in the community. I do prefer prettier's style of not breaking inside of a link name though. This PR is in two parts, the first adds prettier to CI and documents using it, while the second actually formats the docs. When merge conflicts arise, we can drop the last commit and regenerate it with `npx prettier --prose-wrap always --write BENCHMARKS.md CONTRIBUTING.md README.md STYLE.md docs/*.md docs/concepts/**/*.md docs/guides/**/*.md docs/pip/**/*.md`. --------- Co-authored-by: Zanie Blue <contact@zanie.dev>
4.9 KiB
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:
$ uv init hello-world
$ cd hello-world
Alternatively, you can initialize a project in the working directory:
$ mkdir hello-world
$ cd hello-world
$ uv init
This will create the following directory structure:
.
├── 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 immediately.
Commands like uv add and uv run will create a lockfile and 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. Most Python package managers extend the pyproject.toml
standard to support common features, such as development dependencies. These extensions are specific
to each package manager and will need to be converted to uv's format. See the documentation on
project dependencies for more details.
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:
[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.
See the project environment documentation for more details.
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 project
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.
See the lockfile documentation for more details.
Managing dependencies
You can add dependencies to your pyproject.toml with the uv add command. This will also update
the lockfile and project environment:
$ uv add requests
You can also specify version constraints or alternative sources:
# 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:
$ uv remove requests
See the documentation on managing dependencies for more details.
Running commands
uv run can be used to run arbitrary scripts or commands in your project environment. This ensures
that the lockfile and project environment are up-to-date before executing a given command.
For example, to use flask:
$ uv add flask
$ uv run -- flask run -p 3000
Or, to run a script:
# Require a project dependency
import flask
print("hello world")
$ uv run example.py
Alternatively, you can use uv sync to manually update the environment then activate it before
executing a command:
$ uv sync
$ source .venv/bin/activate
$ flask run -p 3000
$ python example.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.
See the documentation on running commands and running scripts in projects for more details.
Next steps
See the projects concept documentation for more details about working with projects.