Migrating commands from Poetry to uv

At Bixoto we used to use Poetry to manage all our Python projects, but we recently started to migrate to uv, which is a lot faster. However, the commands of each tool don’t always match, which can cause some confusion. In this post we provide a partial cheatsheet of the most common commands and their equivalents.

Initialize a repository

  • Poetry: poetry init
  • uv: uv init --bare

uv creates a README.md and a main.py by default; you must use --bare to disable this behavior.

Install dependencies

uv doesn’t have a simple install command, you must use sync with --frozen (to prevent it from updating packages) and --inexact (to keep superfluous packages, which is the default behavior of Poetry).

  • Poetry: poetry install
  • uv: uv sync --frozen --inexact

To synchronize dependencies and remove superfluous packages, use --frozen only:

  • Poetry: poetry sync
  • uv: uv sync --frozen

Update

Poetry has the update command to both update all dependencies or just one, but with uv it’s different:

  • Poetry: poetry update (all dependencies), poetry update <package> (single package)
  • uv: uv lock --upgrade (all dependencies), uv lock --upgrade-package <package> (single package)

Note: in both cases, uv has a shorter option: -U and -P.

Add dependencies

Poetry and uv have the same command to add dependencies, but the option differs when you want to use a different index:

  • Poetry: poetry add [--source $INDEX] ...
  • uv: uv add [--index $INDEX] ...

Remove dependencies

Here too the command are the same:

  • Poetry: poetry remove ...
  • uv: uv remove ...

Run

  • Poetry: poetry run ...
  • uv: uv run ...

Show outdated dependencies

  • Poetry: poetry show --outdated --top-level
  • uv: uv tree --outdated --depth=1

Add another index

Poetry has commands to add other indexes, but uv does not: you must edit pyproject.toml to do it.

  • Poetry: poetry source add $INDEX $URL

Poetry also has a command to do it globally but it’s unclear if it’s feasible with uv:

  • Poetry: poetry config repositories.$INDEX $URL

Publish a package

Poetry allows to build at the same time but uv requires a separate command:

  • Poetry: poetry publish --build --skip-existing [--repository $INDEX]
  • uv: uv build && uv publish [--index $INDEX]

We initially published this document in our internal wiki, but we thought it would be useful to others as well. Commands and options don’t always match, and it can be hard to get used to the new ones after a few years of Poetry usage.