Add a migration guide from pip to uv projects #12382

zanieb · 2025-03-21T21:15:19Z

docs/guides/migration/pip-to-project.md

samypr100 · 2025-03-23T23:58:49Z

docs/guides/migration/pip-to-project.md

+
+Here, all the versions constraints are _exact_. Only a single version of each package can be used.
+The above example was generated with `uv pip compile`, but could also be generated with
+`pip-compile` from `pip-tools`. The `requirements.txt` can also be generated using `pip freeze`, by


Suggested change

`pip-compile` from `pip-tools`. The `requirements.txt` can also be generated using `pip freeze`, by

`pip-compile` from `pip-tools`. The `requirements.txt` can also be generated using `pip freeze` on a pristine environment, by

A little scared to try to explain what a pristine environment is

oconnor663 · 2025-06-04T19:02:55Z

My understanding is that the first half of the doc is saying "you're probably already doing something like this, let's flesh out an example to make sure we're all on the same page, before we suggest what you can do differently". But a lot of the individual lines in that section sound more like "here's what you should do", i.e.:

when your project requires a package, you can install it with pip

It's best practice to create a virtual environment for each project, to avoid mixing packages between them

Would it be better to use the "you might be doing XYZ" tense throughout the first half?

Gankra · 2025-06-04T19:54:58Z

docs/guides/migration/pip-to-project.md

+    If you're familiar with the ecosystem, you can jump ahead to the
+    [requirements file import](#importing-requirements-files) instructions.
+
+## Requirements


Oh this is about requirements-as-in-dependencies, and not requirements-for-following-this-guide? (A bit confusing, but maybe fine if you needed this guide)

This whole section is kinda fascinating to me, explaining how to use not-uv to the explain how to use uv...

Yeah sort of wild but also... necessary I think?

I can consider tweaking this title.

Gankra · 2025-06-04T20:06:04Z

docs/guides/migration/pip-to-project.md

+
+## Requirements
+
+In the most basic form, when your project requires a package, you can install it with `pip`, e.g.:


Suggested change

In the most basic form, when your project requires a package, you can install it with `pip`, e.g.:

`pip` supports installing a package your project needs, e.g.:

Not sure if this is exactly the right wording but I like that the next section leads with "pip supports..." emphasizing that we're talking about a pip workflow, and not like, that uv expects you to use pip.

docs/guides/migration/pip-to-project.md

Gankra · 2025-06-04T20:10:49Z

docs/guides/migration/pip-to-project.md

+    If you're looking to migrate from `pip` and `pip-tools` to uv's drop-in interface or from an
+    existing workflow where you're already using a `pyproject.toml`, those guides are not yet
+    written. See [#5200](https://github.com/astral-sh/uv/issues/5200) to track progress.


Kinda a wild thought, but what if we had all the parts that show how to use pip instead explicitly invoke uv pip to kinda double-up?

(The counter-argument to this is, it might lead to confusion about "wait i AM doing it with uv...")

(Very afraid of the counter-argument, I did consider it :D)

Gankra · 2025-06-04T20:12:15Z

docs/guides/migration/pip-to-project.md

+Here, all the versions constraints are _exact_. Only a single version of each package can be used.
+The above example was generated with `uv pip compile`, but could also be generated with
+`pip-compile` from `pip-tools`.


This is what I'm talking about like with us using uv pip ... everywhere -- what if this was just ambiently demonstrated?

Gankra · 2025-06-04T20:50:29Z

docs/guides/migration/pip-to-project.md

+## `uv.lock`
+


Hmm I kinda feel like these two sections want to be smooshed together.

"The preferred workflow with uv replaces all your requirements.in files with a single* pyproject.toml and all your requirements.txt files with a single uv.lock." kinda thing

Or maybe before we immediately stumble into pyproject.tomls there should be a new higher level header indicating we've entered "the uv zone" with that summary.

docs/guides/migration/pip-to-project.md

Gankra · 2025-06-04T20:57:12Z

docs/guides/migration/pip-to-project.md

+    # via -r requirements.in
+```
+
+When using `-o`, uv will constrain the versions to match the existing output file, if it can.


Gankra · 2025-06-04T21:01:36Z

docs/guides/migration/pip-to-project.md

+To import development dependencies, use the `--dev` flag during `uv add`:
+
+```console
+$ uv add -r requirements-dev.in -c requirements-dev.txt --dev
+```


Interesting, is this smart enough to diff out the dev part from the common dependencies? (Given you previously showed that requirements-dev.in files tend to include requirements.in)

If that diffing works, does this require you to uv add requirements.in first, and then uv add requirements-dev.in --dev, or will you get the same result regardless?

(Given you previously showed that requirements-dev.in files tend to include requirements.in)

Uhhh that might be a problem. I will test. Good catch!

Gankra · 2025-06-04T21:03:54Z

docs/guides/migration/pip-to-project.md

+When in projects, uv will not respect the `VIRTUAL_ENV` variable by default, though you can opt-in
+to it with the `--active` flag.


docs/guides/migration/pip-to-project.md

mkniewallner · 2025-06-04T22:47:44Z

docs/guides/migration/pip-to-project.md

+
+Your existing versions will be retained when producing a `uv.lock` file.
+
+### Importing platform-specific constraints


Maybe it's a way less common use case, but would the same issue applies to Python versions too, for projects that need to support multiple versions of Python? And if so, do you think a specific section would be worth having?

Yeah that problem would apply. I'm not sure 🤔. I don't know if I've seen many requirements files toggled on version. I can try to add a note of some sort.

docs/guides/migration/pip-to-project.md

mkniewallner · 2025-06-04T22:49:42Z

docs/guides/migration/pip-to-project.md

+
+## Project environments
+
+Unlike pip, uv is not centered around the concept of an "active" virtual environment. Instead, uv


Suggested change

Unlike pip, uv is not centered around the concept of an "active" virtual environment. Instead, uv

Unlike `pip`, uv is not centered around the concept of an "active" virtual environment. Instead, uv

docs/guides/migration/index.md

docs/guides/migration/pip-to-project.md

konstin · 2025-06-11T14:14:20Z

docs/guides/migration/pip-to-project.md

+These dependencies can be compiled into a `requirements.txt` file:
+
+```console
+$ pip compile requirements.in -o requirements.txt


Suggested change

$ pip compile requirements.in -o requirements.txt

$ pip-compile requirements.in -o requirements.txt

konstin · 2025-06-11T14:18:33Z

docs/guides/migration/pip-to-project.md

+uv uses a lockfile (`uv.lock`) file to lock package versions. The format of this file is specific to
+uv, allowing uv to support advanced features. It replaces `requirements.txt` files. Unlike
+`requirements.txt` files, the `uv.lock` file can represent arbitrary groups of dependencies, so
+multiple files are not needed to lock development dependencies.


Not specifically here, but we should make a point about how the uv lockfile is always universal, and if only want your platform (let's the backend only runs on linux anyway), you can restrict it with tool.uv.environments. Not sure how common of a need this is and if we need to mention tool.uv.environments, but we should tie the loop about requirements.txt being platform specific.

Co-authored-by: samypr100 <3933065+samypr100@users.noreply.github.com>

Co-authored-by: Mathieu Kniewallner <mathieu.kniewallner@gmail.com> Co-authored-by: Aria Desires <aria.desires@gmail.com>

eli-yip · 2025-07-03T00:38:57Z

docs/guides/migration/pip-to-project.md

+The uv lockfile is always [universal](../../concepts/resolution.md#universal-resolution), so
+multiple files are not needed to
+[lock dependencies for each platform](#platform-specific-dependencies). This ensures that all
+developers


It seems there is something missing here.

Tragic, thanks!

Fixes #12382 (comment)

This MR contains the following updates: | Package | Update | Change | |---|---|---| | [astral-sh/uv](https://github.com/astral-sh/uv) | patch | `0.7.16` -> `0.7.19` | MR created with the help of [el-capitano/tools/renovate-bot](https://gitlab.com/el-capitano/tools/renovate-bot). **Proposed changes to behavior should be submitted there as MRs.** --- ### Release Notes <details> <summary>astral-sh/uv (astral-sh/uv)</summary> ### [`v0.7.19`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#0719) [Compare Source](astral-sh/uv@0.7.18...0.7.19) The **[uv build backend](https://docs.astral.sh/uv/concepts/build-backend/) is now stable**, and considered ready for production use. The uv build backend is a great choice for pure Python projects. It has reasonable defaults, with the goal of requiring zero configuration for most users, but provides flexible configuration to accommodate most Python project structures. It integrates tightly with uv, to improve messaging and user experience. It validates project metadata and structures, preventing common mistakes. And, finally, it's very fast — `uv sync` on a new project (from `uv init`) is 10-30x faster than with other build backends. To use uv as a build backend in an existing project, add `uv_build` to the `[build-system]` section in your `pyproject.toml`: ```toml [build-system] requires = ["uv_build>=0.7.19,<0.8.0"] build-backend = "uv_build" ``` In a future release, it will replace `hatchling` as the default in `uv init`. As before, uv will remain compatible with all standards-compliant build backends. ##### Python - Add PGO distributions of Python for aarch64 Linux, which are more optimized for better performance See the [python-build-standalone release](https://github.com/astral-sh/python-build-standalone/releases/tag/20250702) for more details. ##### Enhancements - Ignore Python patch version for `--universal` pip compile ([#14405](astral-sh/uv#14405)) - Update the tilde version specifier warning to include more context ([#14335](astral-sh/uv#14335)) - Clarify behavior and hint on tool install when no executables are available ([#14423](astral-sh/uv#14423)) ##### Bug fixes - Make project and interpreter lock acquisition non-fatal ([#14404](astral-sh/uv#14404)) - Includes `sys.prefix` in cached environment keys to avoid `--with` collisions across projects ([#14403](astral-sh/uv#14403)) ##### Documentation - Add a migration guide from pip to uv projects ([#12382](astral-sh/uv#12382)) ### [`v0.7.18`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#0718) [Compare Source](astral-sh/uv@0.7.17...0.7.18) ##### Python - Added arm64 Windows Python 3.11, 3.12, 3.13, and 3.14 These are not downloaded by default, since x86-64 Python has broader ecosystem support on Windows. However, they can be requested with `cpython-<version>-windows-aarch64`. See the [python-build-standalone release](https://github.com/astral-sh/python-build-standalone/releases/tag/20250630) for more details. ##### Enhancements - Keep track of retries in `ManagedPythonDownload::fetch_with_retry` ([#14378](astral-sh/uv#14378)) - Reuse build (virtual) environments across resolution and installation ([#14338](astral-sh/uv#14338)) - Improve trace message for cached Python interpreter query ([#14328](astral-sh/uv#14328)) - Use parsed URLs for conflicting URL error message ([#14380](astral-sh/uv#14380)) ##### Preview features - Ignore invalid build backend settings when not building ([#14372](astral-sh/uv#14372)) ##### Bug fixes - Fix equals-star and tilde-equals with `python_version` and `python_full_version` ([#14271](astral-sh/uv#14271)) - Include the canonical path in the interpreter query cache key ([#14331](astral-sh/uv#14331)) - Only drop build directories on program exit ([#14304](astral-sh/uv#14304)) - Error instead of panic on conflict between global and subcommand flags ([#14368](astral-sh/uv#14368)) - Consistently normalize trailing slashes on URLs with no path segments ([#14349](astral-sh/uv#14349)) ##### Documentation - Add instructions for publishing to JFrog's Artifactory ([#14253](astral-sh/uv#14253)) - Edits to the build backend documentation ([#14376](astral-sh/uv#14376)) ### [`v0.7.17`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#0717) [Compare Source](astral-sh/uv@0.7.16...0.7.17) ##### Bug fixes - Apply build constraints when resolving `--with` dependencies ([#14340](astral-sh/uv#14340)) - Drop trailing slashes when converting index URL from URL ([#14346](astral-sh/uv#14346)) - Ignore `UV_PYTHON_CACHE_DIR` when empty ([#14336](astral-sh/uv#14336)) - Fix error message ordering for `pyvenv.cfg` version conflict ([#14329](astral-sh/uv#14329)) </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever MR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this MR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this MR, check this box --- This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).

zanieb added the documentation Improvements or additions to documentation label Mar 21, 2025

zanieb force-pushed the zb/pip-wip branch 3 times, most recently from 1c68c8e to 50084e4 Compare March 21, 2025 21:25

samypr100 reviewed Mar 24, 2025

View reviewed changes

zanieb mentioned this pull request Apr 1, 2025

Improve ux when pip is not present in virtual environments #12604

Open

zanieb temporarily deployed to uv-test-publish April 2, 2025 21:14 — with GitHub Actions Inactive

zanieb mentioned this pull request Apr 10, 2025

How to convert requirements.txt to tool.uv.sources ? #6275

Closed

zanieb mentioned this pull request May 5, 2025

How to create a lock file from installed packages (or from requirements.txt file) #13300

Closed

turbotimon mentioned this pull request May 20, 2025

How do I generate a pyproject.toml/uv.lock from a pip requirements.txt file? #10924

Closed

zanieb force-pushed the zb/pip-wip branch from baaefd0 to 3befc59 Compare May 21, 2025 01:47

zanieb force-pushed the zb/pip-wip branch 2 times, most recently from 4856a51 to e900710 Compare June 4, 2025 15:17

zanieb marked this pull request as ready for review June 4, 2025 15:28

zanieb mentioned this pull request Jun 4, 2025

Write migration guides #5200

Open

Gankra reviewed Jun 4, 2025

View reviewed changes

mkniewallner reviewed Jun 4, 2025

View reviewed changes

zanieb commented Jun 5, 2025

View reviewed changes

docs/guides/migration/pip-to-project.md Outdated Show resolved Hide resolved

zanieb commented Jun 5, 2025

View reviewed changes

docs/guides/migration/pip-to-project.md Outdated Show resolved Hide resolved

zanieb commented Jun 5, 2025

View reviewed changes

docs/guides/migration/pip-to-project.md Outdated Show resolved Hide resolved

zanieb temporarily deployed to uv-test-publish June 5, 2025 13:13 — with GitHub Actions Inactive

zanieb temporarily deployed to uv-test-publish June 6, 2025 17:38 — with GitHub Actions Inactive

konstin approved these changes Jun 11, 2025

View reviewed changes

zanieb and others added 6 commits July 2, 2025 12:02

Add a migration guide from pip to uv projects

318296c

Edits by samypr100

441d65c

Co-authored-by: samypr100 <3933065+samypr100@users.noreply.github.com>

More edits

bde7899

Add nav

3a011f8

..

60149a2

Review

f96d268

Co-authored-by: Mathieu Kniewallner <mathieu.kniewallner@gmail.com> Co-authored-by: Aria Desires <aria.desires@gmail.com>

zanieb added 2 commits July 2, 2025 12:02

Review

3e564bb

Update development deps import

fdb054b

zanieb force-pushed the zb/pip-wip branch from ac5e8d8 to 54bf27c Compare July 2, 2025 17:07

Review

1401d9c

zanieb force-pushed the zb/pip-wip branch from 54bf27c to 1401d9c Compare July 2, 2025 17:10

zanieb merged commit 2f53ea5 into main Jul 2, 2025
78 checks passed

zanieb deleted the zb/pip-wip branch July 2, 2025 17:25

BrewTestBot mentioned this pull request Jul 2, 2025

uv 0.7.19 Homebrew/homebrew-core#228897

Merged

eli-yip reviewed Jul 3, 2025

View reviewed changes

zanieb mentioned this pull request Jul 3, 2025

Finish incomplete sentence in pip migration guide #14432

Merged

zanieb added a commit that referenced this pull request Jul 3, 2025

Finish incomplete sentence in pip migration guide (#14432)

c3f13d2

Fixes #12382 (comment)

	`pip-compile` from `pip-tools`. The `requirements.txt` can also be generated using `pip freeze`, by
	`pip-compile` from `pip-tools`. The `requirements.txt` can also be generated using `pip freeze` on a pristine environment, by


		## Requirements

		In the most basic form, when your project requires a package, you can install it with `pip`, e.g.:

	In the most basic form, when your project requires a package, you can install it with `pip`, e.g.:
	`pip` supports installing a package your project needs, e.g.:

		When in projects, uv will not respect the `VIRTUAL_ENV` variable by default, though you can opt-in
		to it with the `--active` flag.


		Your existing versions will be retained when producing a `uv.lock` file.

		### Importing platform-specific constraints


		## Project environments

		Unlike pip, uv is not centered around the concept of an "active" virtual environment. Instead, uv

	Unlike pip, uv is not centered around the concept of an "active" virtual environment. Instead, uv
	Unlike `pip`, uv is not centered around the concept of an "active" virtual environment. Instead, uv

	$ pip compile requirements.in -o requirements.txt
	$ pip-compile requirements.in -o requirements.txt

Add a migration guide from pip to uv projects #12382

Add a migration guide from pip to uv projects #12382

Uh oh!

Conversation

zanieb commented Mar 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oconnor663 commented Jun 4, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

eli-yip Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

zanieb commented Mar 21, 2025 •

edited

Loading

eli-yip Jul 3, 2025 •

edited

Loading