Skip to main content
Update the project’s environment to match the lockfile.

​
Usage

uv sync [OPTIONS]

​
Description

Sync ensures that all project dependencies are installed and up-to-date with the lockfile. By default, an exact sync is performed: uv removes packages that are not declared as dependencies of the project. Use the --inexact flag to keep extraneous packages. Note that if an extraneous package conflicts with a project dependency, it will still be removed. Additionally, if --no-build-isolation is used, uv will not remove extraneous packages to avoid removing possible build dependencies. If the project virtual environment (.venv) does not exist, it will be created. The project is re-locked before syncing unless the --locked or --frozen flag is provided. uv will search for a project in the current directory or any parent directory. If a project cannot be found, uv will exit with an error. Note that, when installing from a lockfile, uv will not provide warnings for yanked package versions.

​
Options

​
Dependency Selection

​
--extra
string[]
Include optional dependencies from the specified extra name.May be provided more than once.When multiple extras or groups are specified that appear in tool.uv.conflicts, uv will report an error.Note that all optional dependencies are always included in the resolution; this option only affects the selection of packages to install.
​
--all-extras
Include all optional dependencies.When two or more extras are declared as conflicting in tool.uv.conflicts, using this flag will always result in an error.Note that all optional dependencies are always included in the resolution; this option only affects the selection of packages to install.
​
--no-extra
string[]
Exclude the specified optional dependencies, if --all-extras is supplied.May be provided multiple times.
​
--group
string[]
Include dependencies from the specified dependency group.When multiple extras or groups are specified that appear in tool.uv.conflicts, uv will report an error.May be provided multiple times.
​
--no-group
string[]
Disable the specified dependency group.This option always takes precedence over default groups, --all-groups, and --group.May be provided multiple times.Environment variable: UV_NO_GROUP
​
--all-groups
Include dependencies from all dependency groups.--no-group can be used to exclude specific groups.
​
--no-default-groups
Ignore the default dependency groups.uv includes the groups defined in tool.uv.default-groups by default. This disables that option, however, specific groups can still be included with --group.Environment variable: UV_NO_DEFAULT_GROUPS
​
--only-group
string[]
Only include dependencies from the specified dependency group.The project and its dependencies will be omitted.May be provided multiple times. Implies --no-default-groups.
​
--only-dev
Only include the development dependency group.The project and its dependencies will be omitted.This option is an alias for --only-group dev. Implies --no-default-groups.

​
Installation Control

​
--inexact
Do not remove extraneous packages present in the environment.When enabled, uv will make the minimum necessary changes to satisfy the requirements. By default, syncing will remove any extraneous packages from the environment.
​
--no-install-project
Do not install the current project.By default, the current project is installed into the environment with all of its dependencies. The --no-install-project option allows the project to be excluded, but all of its dependencies are still installed. This is particularly useful in situations like building Docker images where installing the project separately from its dependencies allows optimal layer caching.
​
--no-install-workspace
Do not install any workspace members, including the root project.By default, all workspace members and their dependencies are installed into the environment. The --no-install-workspace option allows exclusion of all the workspace members while retaining their dependencies.
​
--no-install-local
Do not install local path dependencies.Skips the current project, workspace members, and any other local (path or editable) packages. Only remote/indexed dependencies are installed. Useful in Docker builds to cache heavy third-party dependencies first and layer local packages separately.
​
--no-install-package
string[]
Do not install the given package(s).By default, all of the project’s dependencies are installed into the environment. The --no-install-package option allows exclusion of specific packages. Note this can result in a broken environment, and should be used with caution.
​
--no-editable
Install any editable dependencies, including the project and any workspace members, as non-editable.Environment variable: UV_NO_EDITABLE

​
Locking Options

​
--locked
Assert that the uv.lock will remain unchanged.Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.Environment variable: UV_LOCKED
​
--frozen
Sync without updating the uv.lock file.Instead of checking if the lockfile is up-to-date, uses the versions in the lockfile as the source of truth. If the lockfile is missing, uv will exit with an error. If the pyproject.toml includes changes to dependencies that have not been included in the lockfile yet, they will not be present in the environment.Environment variable: UV_FROZEN

​
Workspace Options

​
--all-packages
Sync all packages in the workspace.The workspace’s environment (.venv) is updated to include all workspace members.Any extras or groups specified via --extra, --group, or related options will be applied to all workspace members.
​
--package
string[]
Sync for specific packages in the workspace.The workspace’s environment (.venv) is updated to reflect the subset of dependencies declared by the specified workspace member packages.If any workspace member does not exist, uv will exit with an error.
​
--script
path
Sync the environment for a Python script, rather than the current project.If provided, uv will sync the dependencies based on the script’s inline metadata table, in adherence with PEP 723.

​
Environment Options

​
--active
Sync dependencies to the active virtual environment.Instead of creating or updating the virtual environment for the project or script, the active virtual environment will be preferred, if the VIRTUAL_ENV environment variable is set.
​
--python
string
The Python interpreter to use for the project environment.By default, the first interpreter that meets the project’s requires-python constraint is used.If a Python interpreter in a virtual environment is provided, the packages will not be synced to the given environment. The interpreter will be used to create a virtual environment in the project.See uv help python for details on Python discovery and supported request formats.Short form: -p
Environment variable: UV_PYTHON
​
--python-platform
string
The platform for which requirements should be installed.Represented as a “target triple”, a string that describes the target platform in terms of its CPU, vendor, and operating system name, like x86_64-unknown-linux-gnu or aarch64-apple-darwin.WARNING: When specified, uv will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform.

​
Output Options

​
--output-format
string
default:"text"
Select the output format.Options:
  • text - Display the result in a human-readable format
  • json - Display the result in JSON format

​
Validation Options

​
--check
Check if the Python environment is synchronized with the project.If the environment is not up to date, uv will exit with an error.
​
--dry-run
Perform a dry run, without writing the lockfile or modifying the project environment.In dry-run mode, uv will resolve the project’s dependencies and report on the resulting changes to both the lockfile and the project environment, but will not modify either.

​
Examples

​
Basic sync

uv sync
Syncs the project environment with the lockfile, creating the environment if needed.

​
Sync with extras

uv sync --extra dev --extra test
Syncs including optional dependencies from the dev and test extras.

​
Sync all extras

uv sync --all-extras

​
Sync only development dependencies

uv sync --only-dev
Installs only the development dependencies, excluding the project and its runtime dependencies.

​
Sync with frozen lockfile

uv sync --frozen
Syncs using the existing lockfile without updating it. Fails if the lockfile is missing.

​
Sync without removing packages

uv sync --inexact
Installs required packages but doesn’t remove extraneous ones.

​
Sync all workspace packages

uv sync --all-packages

​
Sync specific workspace packages

uv sync --package pkg1 --package pkg2

​
Sync for a Python script

uv sync --script my_script.py
Syncs dependencies based on the script’s PEP 723 inline metadata.

​
Check sync status

uv sync --check
Checks if the environment is synchronized without making changes.

​
Dry run

uv sync --dry-run
Shows what would be changed without actually modifying anything.

​
Common Patterns

​
Docker layer caching

Install dependencies first, then the project: 
# Copy only dependency files
COPY pyproject.toml uv.lock ./

# Install dependencies (cached layer)
RUN uv sync --no-install-project

# Copy project code
COPY . .

# Install project
RUN uv sync

​
Sync with specific dependency groups

# Include specific groups
uv sync --group test --group docs

# Exclude specific groups
uv sync --all-groups --no-group heavy

​
Local development workflow

# Sync with all extras and dev dependencies
uv sync --all-extras

​
CI/CD workflow

# Ensure lockfile is up to date
uv sync --locked

​
Install only third-party packages

# Skip local packages (useful for Docker caching)
uv sync --no-install-local
  • uv lock - Update the project lockfile
  • uv add - Add dependencies to the project
  • uv remove - Remove dependencies from the project
  • uv run - Run a command in the project environment

Build docs developers (and LLMs) love

Get started for freeTalk to us