uv vai Poetry? Nopeampi asennus ei yksin ratkaise Python-työnkulkua

9. lokakuuta 2026 klo 13.00|Kirjoittaja: QUASAn toimitus|4 min lukuaika

uv oli Python Dependency Management Benchmarkin toukokuussa 2025 julkaisemassa kylmäasennusvertailussa Poetrya nopeampi: Apple Silicon -ympäristössä Python 3.11.6:lla ajat olivat 0,66 ja 2,20 sekuntia. Uuteen projektiin uv on varteenotettava valinta, jos samaan työnkulkuun halutaan riippuvuuksien, virtuaaliympäristön ja Python-version hallinta. Toimivan Poetry-projektin siirtoa yksittäinen nopeusluku ei ratkaise, sillä myös määritykset, CI ja mahdollinen paketointi on sovitettava uuteen työkaluun.

Vertailussa molemmat työkalut merkittiin toistettaviksi: raportin mukaan ympäristöjen tiivisteet pysyivät samoina kolmella ajokerralla. Repositorio tarjoaa uusimista varten myös Hyperfine-pikakokeen, jossa tehdään lämmittelyajo ja poistetaan .venv ennen asennusskriptin suoritusta. Ohje ei yksilöi, tyhjennettiinkö pakettien latausvälimuistit raportoitujen kylmäasennuslukujen mittauksessa. Lukuja kannattaa siksi pitää kyseisen testin tuloksina, ei ennusteena oman projektin asennusajasta.

Lukitus ja ympäristö: mitä projektissa vaihtuu?

Poetryn käyttöohjeen mukaan poetry install kirjoittaa ratkaistut riippuvuusversiot poetry.lock-tiedostoon ja käyttää olemassa olevan lukituksen versioita myöhemmissä asennuksissa. Poetry luo virtuaaliympäristön oletuksena välimuistihakemistonsa alle, mutta sen voi määrittää myös projektin sisään. Työkalu tarvitsee käytettävissä olevan, projektin versiovaatimuksen täyttävän Python-tulkin; se ei asenna tulkkia käyttäjän puolesta.

uv:n projektiohjeessa pyproject.toml sisältää projektin määritykset, uv.lock tarkat ratkaistut riippuvuudet ja .venv projektin virtuaaliympäristön. .python-version kertoo, mitä Python-versiota ympäristön luonnissa käytetään. uv run tarkistaa ennen komennon suorittamista lukitustiedoston ja ympäristön ajantasaisuuden; uv sync päivittää ympäristön erillisenä komentona. Ympäristön sijainti ja synkronoinnin tapa siis muuttuvat, vaikka kummallakin työkalulla voi työskennellä lukittujen riippuvuuksien kanssa.

Poetry.lockia ei voi muuttaa uv.lockiksi nimeämällä tiedosto uudelleen. Kun uv ratkaisee riippuvuudet omaan lukitustiedostoonsa, tuloksena olevat versiot voivat poiketa aiemmasta lukituksesta, vaikka pyproject.toml sallisi kummatkin. Siirrossa vanha lukitus on hyödyllinen vertailukohta, kunnes uusi ympäristö ja testit on todettu toimiviksi; CI:ssä käytettävä lukitus on tämän jälkeen valittava selvästi.

Sovellus ja kirjasto tarvitsevat lukitusta eri tavoin

Sovelluksessa kehittäjä hallitsee tavallisesti myös testaus- ja käyttöönottoympäristöä. Lukitustiedosto auttaa pitämään näissä vaiheissa samat riippuvuusversiot, kunhan kehittäjien ja CI:n asennuskomennot todella käyttävät sitä. Siksi Poetry-sovelluksen siirron hyöty syntyy vasta koko asennusketjussa: uv.lockin lisääminen repositorioon ei yksin vaihda CI:n käyttämiä komentoja tai siellä luotavaa ympäristöä.

Kirjaston käyttäjän sovellus ratkaisee riippuvuutensa julkaistun kirjaston versiorajojen perusteella eikä peri kirjastoprojektin lukitustiedostoa. Kirjaston oma lukitus on silti hyödyllinen sen kehityksen ja testien toistamisessa. Siirron ratkaiseva kysymys on tällöin, vastaavatko julkaistun paketin riippuvuusmetadata, valinnaiset riippuvuudet ja sisältö aiempaa julkaisua. Nopeampi paikallinen asennus ei korvaa tätä tarkistusta.

Migraatiokartta: komennot ja tiedostot

Yksinkertaisen projektin komentovaihto on lyhyt, mutta pyproject.toml voi sisältää määrityksiä, joita uusi komentorivi ei tulkitse samalla tavalla. Poetryn pyproject-ohjeessa kuvataan muun muassa omat pakettilähteet, riippuvuusryhmät sekä packages-, include- ja exclude-määritykset. Niiden merkitys pitää säilyttää erikseen, jos projekti siirtyy pois Poetryn määritystavasta.

Riippuvuuden lisäys: poetry add vaihtuu uv add -komentoon. Ryhmiin lisättäessä kummassakin voi käyttää --group-valintaa, mutta ryhmien sisältö ja asennuksessa valittavat ryhmät on sovitettava projektin nykyiseen käytäntöön.
Lukitus: poetry.lock vaihtuu uv.lock-tiedostoon, jonka uv lock tuottaa. Tämä on uusi riippuvuuksien ratkaisu, joten olennaiset versiot ja mahdolliset lähde-erot on verrattava vanhaan lukitukseen.
Asennus ja suoritus: poetry install -vaiheen tilalle tulee yleensä uv sync. Esimerkiksi poetry run pytest vaihtuu uv run pytest -komentoon. CI:n asennus- ja testivaiheet on muutettava yhdessä, jotta ne käyttävät samaa ympäristöä.
Tulkki ja ympäristö: Poetry käyttää järjestelmästä saatavaa sopivaa Python-tulkkia ja oletusarvoisesti välimuistissa olevaa virtuaaliympäristöä. uv-projektissa ympäristö on tavallisesti .venv, ja .python-version voi määrittää sille valittavan tulkin version.
Projektimääritykset: pyproject.toml säilyy, mutta Poetrylle ominaiset lähde- ja paketointikohdat eivät muutu uv:n määrityksiksi komentojen vaihdolla. Erityisesti yksityiset pakettilähteet ja julkaistavan paketin tiedostovalinnat tarvitsevat oman tarkistuksensa.

Jos siirto tehdään, uusi lukitus kannattaa tuottaa erillisessä muutoksessa ja ajaa sillä projektin nykyinen testi- ja rakennusketju. Näin työkalun vaihdosta johtuvat erot erottuvat samanaikaisista riippuvuuspäivityksistä. Mittaa myös oman projektin asennus samalla Python-versiolla ja samoilla välimuistiehdoilla kummallakin työkalulla, jos nopeus on siirron peruste.

Julkaisu voi kasvattaa siirron työmäärää

Julkaistavassa kirjastossa ympäristön synkronointi on vain osa työnkulkua. uv:n julkaisuohje erottaa uv build -komennolla rakennettavat jakelupaketit ja uv publish -komennolla tehtävän latauksen rekisteriin. Rakennusjärjestelmä määritetään pyproject.toml-tiedostossa; uv:n käyttö projektinhallintaan ei yksin määrää, mitkä moduulit ja resurssit päätyvät lähdejakeluun tai wheel-pakettiin.

Jos Poetry-projekti määrittää erikseen mukaan otettavat paketit, tiedostot tai yksityisen julkaisukohteen, siirron hyväksymiskriteerinä kannattaa käyttää valmista jakelupakettia ja toimivaa julkaisuketjua. Paketin sisältö ja riippuvuusmetadata on verrattava aiempaan, ja CI:n rekisteriosoite sekä tunnistautuminen on sovitettava uusiin komentoihin. Sovelluksella, jota ei julkaista kirjastona, tätä työvaihetta ei välttämättä ole, joten sen siirto voi olla selvästi kevyempi.

Milloin uv kannattaa valita?

Uudessa projektissa uv on luonteva valinta, jos sen projektikohtainen ympäristö, lukitus ja tulkin valinta sopivat tiimin työhön. Olemassa olevassa Poetry-sovelluksessa siirto on perusteltu, kun nopeushyöty toistuu omalla riippuvuusjoukolla ja CI:n sekä määritysten muutos on hallittava. Kirjastossa ja vahvasti Poetryn paketointimäärityksiin nojaavassa projektissa painavin mittari on julkaistun paketin vastaavuus: se kertoo siirron onnistumisesta enemmän kuin yhden ympäristön asennusaika.

Lue myös:

Jaa: