Understanding the Difference Between uv lock --upgrade and uv sync in Python Dependency Management

Learn how `uv lock --upgrade` and `uv sync` commands differ in managing Python package versions and environments with `uv`.
---
This video is based on the question https://stackoverflow.com/q/79475051/ asked by the user 'n3wbie' ( https://stackoverflow.com/u/6666611/ ) and on the answer https://stackoverflow.com/a/79475140/ provided by the user 'Gwang-Jin Kim' ( https://stackoverflow.com/u/9690090/ ) at 'Stack Overflow' website. Thanks to these great users and Stackexchange community for their contributions.

Visit these links for original content and any more details, such as alternate solutions, latest updates/developments on topic, comments, revision history etc. For example, the original title of the Question was: What's the difference between uv lock --upgrade and uv sync?

Also, Content (except music) licensed under CC BY-SA https://meta.stackexchange.com/help/l...
The original Question post is licensed under the 'CC BY-SA 4.0' ( https://creativecommons.org/licenses/... ) license, and the original Answer post is licensed under the 'CC BY-SA 4.0' ( https://creativecommons.org/licenses/... ) license.

If anything seems off to you, please feel free to drop me a comment under this video.
---
Introduction

When managing Python project dependencies with uv, it's essential to understand the distinct roles of uv lock --upgrade and uv sync. Both commands interact with dependency versions but serve different purposes.



What Does uv lock --upgrade Do?

Purpose: Updates the uv.lock file, which records the exact package versions for your project.

Functionality: Allows upgrading pinned or existing package versions in the lock file.

Important: It does not modify or upgrade packages currently installed in your environment.

Think of uv lock --upgrade as refreshing your dependency snapshot without changing your active Python environment.



What Does uv sync Do?

Purpose: Synchronizes your Python environment’s installed packages to match the versions recorded in the uv.lock file.

Functionality: Installs, updates, or removes packages as necessary to align the environment with the lock file.

Important: This command actually alters your environment's packages.

In other words, uv sync realizes the lock file's specification in your active Python setup.



How They Work Together

Run uv lock --upgrade to refresh your lock file with the latest compatible package versions.

Run uv sync to update your environment to match those versions.

This two-step approach helps you control when and how your project's dependencies and environments are updated.



Getting More Help

For detailed command usage, run:

[[See Video to Reveal this Text or Code Snippet]]

and

[[See Video to Reveal this Text or Code Snippet]]

These commands provide comprehensive guidance on all flags and options.



Summary

uv lock --upgrade: Updates the lock file versions only.

uv sync: Updates your environment packages to match the lock file.

Understanding this distinction helps maintain reproducible environments and predictable dependency upgrades in Python projects managed with uv.