ASDF + Poetry to UV Migration Guide

ASDF + Poetry has been a powerful combo for managing python projects. Poetry focuses on dependency management but doesn’t handle Python version management. To ensure your project used the correct version of Python, you needed an external tool like ASDF or pyenv. UV, a python package and project manager, is built on ruff. It supports almost all the features of poetry and as well as python version management. As such, UV offers simplified dependency management, better performance, and a modern take on package handling. This guide will walk you through the migration process step by step.

Why Switch to uv?

Before we get into the how, let’s talk about the why. Uv has gained popularity due to:

• Efficiency: Faster dependency resolution.
• Integrated environment management: Removes the need for external tools like asdf for Python version management.

Migrating from Poetry to uv

Follow these steps to migrate your project from Poetry and asdf to uv:

1. Install uv

Begin by installing uv on your machine. If you’re on macOS, the easiest way is through Homebrew:

brew install uv

2. Update pyproject.toml for uv Compatibility

Use the migration utility provided by uv to convert your existing pyproject.toml file into a uv-compatible format:

uvx migrate-to-uv

This handy tool will analyze your pyproject.toml file and make the necessary modifications so it works seamlessly with uv.

3. Fix JFrog Connectivity (if applicable)

If your project relies on JFrog Artifactory or any other private pypi registries for dependency hosting, you’ll need to set the required environment variables. Add the following lines to your ~/.zprofile (or ~/.profile):

echo "export UV_INDEX_JFROG_USERNAME=[YOUR USER NAME]" >> ~/.zprofile
echo "export UV_INDEX_JFROG_PASSWORD=[JFROG PAT]" >> ~/.zprofile
source ~/.zprofile

Replace [YOUR USER NAME] and [JFROG PAT] with your credentials.

4. Verify Everything Works

Remove the old poetry.lock file and sync dependencies with uv.

rm poetry.lock
uv sync

Run your project to confirm that everything is working as expected!

Comparing Poetry Commands with uv

Migrating to a new tool always involves learning some new commands. To help you hit the ground running, here’s a handy comparison of Poetry commands and their uv equivalents:

References:

I found following blogs to very helpful

1. Loopwerk: Poetry versus uv
2. Speeding up my python workflow