chore: Adopt uv as package manager

[FBruzzesi]

Description

Related discord thread

Closes #3626

---

4.7k over 5.1k lines are due to committing the uv.lock file - The main reason for that is that these days security vulnerabilities are a nightmare and we could get some automatic dependabot alerts if we have a lock file. This is the same reason for which I started to pin some non-core dependencies (e.g. pytest has vulnerabilities fixed in v9.0.3).

uv audit is still experimental but also a good start to run periodically locally to check for known vulnerabilities

What type of PR is this? (check all applicable)

• 💾 Refactor
• ✨ Feature
• 🐛 Bug Fix
• 🔧 Optimization
• 📝 Documentation
• ✅ Test
• 🐳 Other

[MarcoGorelli]

sure, it's probably about time i learned to use uv properly 😄

[camriddell]

Thank you for all of your work @FBruzzesi this is shaping up really well. I have a few questions & comments that should be addressed on:

1. Changes made to existing dependency versions in pyproject.toml
2. Documentation for running the test suite
3. Changes that appear unrelated to the goal of the PR (adopting UV)

[MarcoGorelli]

thanks for working on this

tbh i'm not totally sold on the dependency management, as show dependencies doesn't necessarily match what gets run when you add in --extra, e.g.

(narwhals-dev) mgorelli@marcoslaptop:~/narwhals-dev$ uv tree --group core-tests | grep pandas
Resolved 167 packages in 3ms
│   ├── pandas v3.0.3 (extra: dataframe)
│   ├── pandas v3.0.3 (extra: connect) (*)
│   ├── pandas v3.0.3 (group: core-tests) (*)
├── pandas v3.0.3 (group: core-tests) (*)
(narwhals-dev) mgorelli@marcoslaptop:~/narwhals-dev$ uv run --group core-tests --extra modin python -c 'import pandas; print(pandas.__version__)'
2.3.3

So, i'm a little hesitant about replacing the github workflows (the rest of the changes look fine though)

[FBruzzesi]

thanks for working on this

tbh i'm not totally sold on the dependency management, as show dependencies doesn't necessarily match what gets run when you add in --extra, e.g.

(narwhals-dev) mgorelli@marcoslaptop:~/narwhals-dev$ uv tree --group core-tests | grep pandas
Resolved 167 packages in 3ms
│   ├── pandas v3.0.3 (extra: dataframe)
│   ├── pandas v3.0.3 (extra: connect) (*)
│   ├── pandas v3.0.3 (group: core-tests) (*)
├── pandas v3.0.3 (group: core-tests) (*)
(narwhals-dev) mgorelli@marcoslaptop:~/narwhals-dev$ uv run --group core-tests --extra modin python -c 'import pandas; print(pandas.__version__)'
2.3.3

So, i'm a little hesitant about replacing the github workflows (the rest of the changes look fine though)

Thank @MarcoGorelli that was the reason why I was using uv pip compile, which allows to pass extras other than groups. The case here is modin forcing pandas to be below v3. I will keep looking for a way of doing this

[FBruzzesi]

@MarcoGorelli uv export seems to play nice and reads from the lock file as uv run does.

Need to take care of some pre-release deps in the lock file. Not sure I can make it today.
I will read any other feedback

[FBruzzesi]

Hey everyone, thanks for all the reviews and iterations you are doing. I think I addressed all the open threads, but there are quite a few so I might have missed some.

There are quite a few follow ups (Thanks @dangotbanned for tracking them all in different issues).

Some comments to address:

• renovate bot: we will need to investigate it, and in general decide when/how to bump dependencies in the lock file
• Min version pinning in pyproject.toml: I aim to be able to run uv audit --resolution=lowest, or at least uv audit --resolution=lowest-direct, both of which require min version pinning. For extras it's clear what they should be, for dev dependencies I picked versions that should still be compatible with python 3.10
• On the sys.path and pre-commit arguments (which I didn't change at the end): I would be happy to investigate if prek deals with it better

---

Let me know if there is something else to address

[MarcoGorelli]

why does the uv run step have --with "pyspark==3.5.0" but uv export doesn't?

should be make a little cli util which does both uv export and then uv run with the same groups and extras, to ensure that they are always in sync?

[dangotbanned]

snap 😉

I thought this too!

dangotbanned
19/05/2026, 10:13
#3608 (comment)

If you come up with a solution for this, it might be helpful to have it as MAKEFILE command/ nested reusable workflow to allow passing the requirements/constraints in a single command (if that's possible?)

dangotbanned
19/05/2026, 19:22
So what I mean is that say for this example:

Current

      - name: Show dependencies
        run: uv export --no-annotate --no-hashes --group extreme-minimum-versions
      - name: Run pytest
        run: |
          uv run --group extreme-minimum-versions \
          pytest tests --cov=src --cov=tests --cov-fail-under=50 --runslow \
          --constructors="pandas,pyarrow,polars[eager],polars[lazy],duckdb"

Reusable

If you instead could write something like:

      - name: Run pytest
        run: |
          make run-ci --group extreme-minimum-versions \
          pytest tests --cov=src --cov=tests --cov-fail-under=50 --runslow \
          --constructors="pandas,pyarrow,polars[eager],polars[lazy],duckdb"

Where run-ci would expand to something like this:

$ uv export --no-annotate --no-hashes --group <pass-the-group-here>
$ uv run --group <pass-the-group-here> \
  pytest tests --cov=src --cov=tests --cov-fail-under=50 --runslow \
  --constructors="pandas,pyarrow,polars[eager],polars[lazy],duckdb"

But I'm fine with just adding it as a follow-up for #3635

[FBruzzesi]

I didn't want to create yet another dependency group just to pin pyspark 3.5.0
uv export doesn't have a --with option and this is the only such case across all GHA if I remember correctly

[FBruzzesi]

Addressed in 644d62b

Actions are not running

Update: Triggered with empty commit

[dangotbanned]

@FBruzzesi I still approve 😄

Nice diff on (644d62b) btw 👏

[camriddell]

Thanks for all of the discussion and edits along the way. We're looking to be in good form now, thanks!

[MarcoGorelli]

thanks, looks like everything's resolved

haven't checked all the details, but the issues i'd brought up have been resolved, and there's another two approvals, so happy to go forwards with this if you're all happy 🙌