Hello there! First real docs PR for uv.
1. I expect this will be rewritten a gazillion times to have a
consistent tone with the rest of the docs, despite me trying to stick to
it as best as I could. Feel free to edit!
2. I went super on the verbose mode, while also providing a callout with
a TLDR on top. Scrap anything you feel it's redundant!
3. I placed the guide under `integrations` since Charlie added the
FastAPI integration there.
## Summary
<!-- What's the purpose of the change? What does it do, and why? -->
Addresses #5945
## Test Plan
<!-- How was it tested? -->
I just looked at the docs on the dev server of mkdocs if it looked nice.
**I could not test the commands that I wrote work** outside of macOS. If
someone among contributors has a Windows/Linux laptop, it should be
enough, even for the GPU-supported versions: I expect the installation
will just break once torch checks for CUDA (perhaps even at runtime).
---------
Co-authored-by: Santiago Castro <bryant1410@gmail.com>
Co-authored-by: Charlie Marsh <charlie.r.marsh@gmail.com>
## Summary
Figured this could be helpful to mention in the documentation, as it
might not be obvious that this is possible.
## Test Plan
Tested the commands locally.
This pull request includes updates to the `docs/guides/tools.md` file to
provide more detailed instructions on how to pull from a git repository
using different options, using the `git+https` scheme support.
It follows [asking a question in the Discord
chat](https://discord.com/channels/1039017663004942429/1060247592765759518/1303270516588806214)
and getting some useful guidance that was not in the docs, but makes
some very useful features of `uv` easier to discover.
## Summary
Tweaks to documentation:
* Added instructions on how to pull the latest commit from a specific
named branch.
* Added instructions on how to pull a specific tag.
* Added instructions on how to pull a specific commit.
## Summary
This commit adds Google Artifact Registry authentication instructions
for both basic HTTP authentication and keyring methods.
## Test Plan
Locally tested using both methods.
## Summary
Renovate recently gained support for updating dependencies defined using
PEP 723 (https://github.com/renovatebot/renovate/pull/31266). Since uv
supports this format, I thought it could be nice to mention support for
it in the integrations documentation as well. I took the occasion to
make the page a bit more structured as well.
## Test Plan
Ran Renovate on https://github.com/mkniewallner/renovate-pep723, which
created https://github.com/mkniewallner/renovate-pep723/pull/2 that
updates a dependency defined using PEP 723. But I'll re-run some tests
again once the changes are released on Renovate cloud GitHub app just in
case.
## Summary
This is a trivial, one line documentation change that fixes the
following documentation bug.
The current documentation suggests this for adding a git dependency
```
# Add a git dependency
uv add requests --git https://github.com/psf/requests
```
Executing what is suggested with `uv` version `0.4.18` results in this
error message
```
uv add requests --git https://github.com/psf/requests
error: unexpected argument '--git' found
```
The working approach is to add the git depency like this:
```
uv add git+https://github.com/psf/requests
```
## Test Plan
I manually tested the command suggested currently in the guide against
my change.
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
Documentation for GitLab integration, reliant on the new tags introduced
in https://github.com/astral-sh/uv/pull/6053
## Test Plan
<!-- How was it tested? -->
---------
Co-authored-by: David Fritzsche <9479371+davidfritzsche@users.noreply.github.com>
Co-authored-by: Zanie Blue <contact@zanie.dev>
## Summary
It was all too easy to just copy the non-qualified name of the Docker
images and wonder why they couldn't be found – well, because they're on
`ghcr.io`, and you need to read the prose before the list to figure that
out.
## Test Plan
No plan.
This PR adds support for ```uv init --script```, as defined in issue
#7402 (started working on this before I saw jbvsmo's PR). Wanted to
highlight a few decisions I made that differ from the existing PR:
1. ```--script``` takes a path, instead of a path/name. This potentially
leads to a little ambiguity (I can certainly elaborate in the docs,
lmk!), but strictly allowing ```uv init --script path/to/script.py```
felt a little more natural than allowing for ```uv init --script path/to
--name script.py``` (which I also thought would prompt more questions
for users, such as should the name include the .py extension?)
2. The request is processed immediately in the ```init``` method,
sharing logic in resolving which python version to use with ```uv add
--script```. This made more sense to me — since scripts are meant to
operate in isolation, they shouldn't consider the context of an
encompassing package should one exist (I also think this decision makes
the relative codepaths for scripts/packages easier to follow).
3. No readme — readme felt a little excessive for a script, but I can of
course add it in!
---------
Co-authored-by: João Bernardo Oliveira <jbvsmo@gmail.com>
## Summary
Related discussion: #5731
This adds a warning section for caching on non-ephemeral (e.g. ec2) self
hosted github runners.
## Test Plan
Prettier was ran on the file.
---------
Co-authored-by: Zanie Blue <contact@zanie.dev>
## Summary
Closes https://github.com/astral-sh/uv/issues/7027
* When displaying the file structure of a uv-managed project show the
`.python-version` file which is now created by default.
* Mention the purpose of the `.python-version` file in `Guides/Working
on projects/Project structure`
* In `Concepts/Python versions/Project python versions`, changed
sentence about `.python-version` file to reflect the fact it is included
by default so is likely to be present.
## Summary
Update the extended docker example to use bind mounts and avoid creating
extra layers and avoid copying files into layers
This is in line with the official Docker templates for Python
applications (you can try them out using `docker init`. I found them
very helpful!)
## Summary
Closes https://github.com/astral-sh/uv/issues/5610
This PR introduces additional images with the uv/uvx binaries from
scratch for both amd64/arm64 and make the mapping easy to configure by
generating the Dockerfile on the fly. This approach focuses on
minimizing CI time by taking advantage of dedicating a worker per
mapping (20-30s~ per job).
This PR also fixes `org.opencontainers.image.version` for all tags
(including the one from `scratch) to contain the right release version
instead of branch name `main` (default when no tag patterns are
specified).
For example, on release `x.y.z`, this will publish the following image
tags with format `ghcr.io/astral-sh/uv:{tag}` with manifests for both
amd64/arm64. This also include `x.y` tags for each respective additional
tag.
* From **scratch**: `latest`, `x.y.z`, `x.y` (currently being published)
* From **alpine:3.20**: `alpine`, `alpine3.20`, `x.y.z-alpine`,
`x.y.z-alpine3.20`
* From **debian:bookworm-slim**: `debian-slim`, `bookworm-slim`,
`x.y.z-debian-slim`, `x.y.z-bookworm-slim`
* From **buildpack-deps:bookworm**: `debian`, `bookworm`,
`x.y.z-debian`, `x.y.z-bookworm`
* From **python:3.12-alpine**: `python3.12-alpine`,
`x.y.z-python3.12-alpine`
* From **python:3.11-alpine**: `python3.11-alpine`,
`x.y.z-python3.11-alpine`
* From **python:3.10-alpine**: `python3.10-alpine`,
`x.y.z-python3.10-alpine`
* From **python:3.9-alpine**: `python3.9-alpine`,
`x.y.z-python3.9-alpine`
* From **python:3.8-alpine**: `python3.8-alpine`,
`x.y.z-python3.8-alpine`
* From **python:3.12-bookworm**: `python3.12-bookworm`,
`x.y.z-python3.12-bookworm`
* From **python:3.11-bookworm**: `python3.11-bookworm`,
`x.y.z-python3.11-bookworm`
* From **python:3.10-bookworm**: `python3.10-bookworm`,
`x.y.z-python3.10-bookworm`
* From **python:3.9-bookworm**: `python3.9-bookworm`,
`x.y.z-python3.9-bookworm`
* From **python:3.8-bookworm**: `python3.8-bookworm`,
`x.y.z-python3.8-bookworm`
* From **python:3.12-slim-bookworm**: `python3.12-slim-bookworm`,
`x.y.z-python3.12-slim-bookworm`
* From **python:3.11-slim-bookworm**: `python3.11-slim-bookworm`,
`x.y.z-python3.11-slim-bookworm`
* From **python:3.10-slim-bookworm**: `python3.10-slim-bookworm`,
`x.y.z-python3.10-slim-bookworm`
* From **python:3.9-slim-bookworm**: `python3.9-slim-bookworm`,
`x.y.z-python3.9-slim-bookworm`
* From **python:3.8-slim-bookworm**: `python3.8-slim-bookworm`,
`x.y.z-python3.8-slim-bookworm`
## Summary
- Fixed the directory structure and commands for the second scenario
#6833
- Added a headline "Migrating an existing FastAPI project" because the
first part looks like a migration scenario, but didn't have its own
section before.
- Added explicit `--app` flags to commands to emphasize that the
commands create an Application project. Although maybe unnecessary
considering that `--app` is now default.
- Added instructions for testing that the dev server and Docker image
work correctly
- Took the liberty of adding a `project` at the root of all directory
structures and appropriate commands.
- With explicitly defined root directory it is easier to differentiate
between the `project` root directory and FastAPI's `app` directory.
- Without it it could be less obvious for developers less familiar with
FastAPI. Had a similar issue when started using Django several years
ago.
- If I left `app` in the command, then after copying the **app
directory** from https://github.com/astral-sh/uv-fastapi-example the
path would be `app/app/...`.
- Cleaned up glyphs in tree sctructures that were copied from FastAPI
docs.
## Caveats
- On project initialization `hello.py` is created. It is not reflected
in directory structure trees in this PR and may be slightly confusing
for developers less familiar with uv.
- I believe it will be soon addressed in #6750 and after that the docs
will reflect actual directory structure.
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
This adds explicit information about using `uv` with AWS CodeArtifact
(both as an extra index to fetch private packages and also to publish
packages using `twine`).
## Test Plan
I'm currently using this setup with several private projects that use
CodeArtifact.
---------
Co-authored-by: Zanie Blue <contact@zanie.dev>
When not using a python base image and using alpine, you need to install
python by yourself. You should also pin the python version when doing
so; currently, i see only python 3.12 in the alpine repository.
baggiponte
Zanie Blue
RafaelWO
Mathieu Kniewallner
Chris Adams
konsti
Udi Oron
Stevie Gayet
Charlie Marsh
Aditya Pratap Singh
samypr100
Sigurd Spieckermann
Volker Hilsenstein
Victorien
Jonas Vacek
Javad Zarezadeh
Aarni Koskela
tfsingh
my1e5
David Bern
Ed Morley
David Cardozo
Den Kasyanov
Shantanu
Franco Mariluis