uv के साथ एक तेज़, पुनरुत्पाद्य Python प्रोजेक्ट कैसे सेट करें

जब आप Claude Code या Codex जैसे किसी AI कोडिंग एजेंट को किसी Python प्रोजेक्ट पर लगाते हैं, तो आधी मुश्किल का मॉडल से कोई लेना-देना नहीं होता। यह वातावरण से आती है: गायब पैकेज, गलत Python वर्शन, एक ऐसा virtualenv जिसे एजेंट सक्रिय करना भूल गया, या एक टीममेट जिसका कहना है "मेरी मशीन पर तो चलता है।" इसका हल है एक ऐसा प्रोजेक्ट जो डिफ़ॉल्ट रूप से पुनरुत्पाद्य (reproducible) हो, और आज इसे पाने का सबसे तेज़ तरीका है uv, Astral का Rust-आधारित Python टूलचेन।

uv pip, venv, pip-tools, और pyenv को एक ही तेज़ कमांड से बदल देता है, और यह एक lockfile लिखता है ताकि बिल्कुल वही डिपेंडेंसी ट्री हर जगह इंस्टॉल हो। यह गाइड आपको कुछ ही मिनटों में शून्य से एक लॉक किए हुए, चलने योग्य प्रोजेक्ट तक पहुंचा देती है।

एजेंट के लिए वातावरण क्यों मायने रखता है

एक AI एजेंट आपके शेल में कमांड चलाता है और जो त्रुटियां वापस आती हैं उन्हें पढ़ता है। अगर आपके प्रोजेक्ट में कोई घोषित डिपेंडेंसी नहीं है और कोई पिन किया हुआ Python वर्शन नहीं है, तो एजेंट को अनुमान लगाना पड़ता है — और एक गलत अनुमान उसे पैकेज ग्लोबली इंस्टॉल करने या गलत इंटरप्रेटर संपादित करने की भूल-भुलैया में भेज देता है। एक ऐसा प्रोजेक्ट जिसमें pyproject.toml और uv.lock हो, एजेंट को सच्चाई का एक ही स्रोत देता है: वह uv sync चला सकता है, सही पैकेज प्राप्त कर सकता है, और आगे बढ़ सकता है। आप अपना समीक्षा समय लॉजिक पर खर्च करते हैं, न कि वातावरण की पुरातत्व खुदाई पर।

uv इंस्टॉल करें

macOS या Linux पर:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell) पर:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

uv एक एकल स्व-निहित (self-contained) बाइनरी है, इसलिए कॉन्फ़िगर करने के लिए और कुछ नहीं है।

एक कमांड में प्रोजेक्ट शुरू करें

uv init weather-cli
cd weather-cli

यह एक कार्यशील प्रोजेक्ट का ढांचा बनाता है: मेटाडेटा और डिपेंडेंसी के लिए एक pyproject.toml, एक .python-version फ़ाइल, एक शुरुआती main.py, एक README.md, और एक .gitignore। आपको हाथ से कोई virtualenv बनाने या सक्रिय करने की ज़रूरत नहीं है — जैसे ही आपको आवश्यकता होती है, uv आपके लिए एक .venv प्रबंधित कर देता है।

डिपेंडेंसी जोड़ें (और lockfile क्यों मायने रखता है)

uv add requests

यह एक साथ तीन काम करता है: pyproject.toml में requests दर्ज करता है, पूरे डिपेंडेंसी ट्री को हल करता है, और सटीक, क्रॉस-प्लेटफ़ॉर्म पिन किए गए वर्शन के साथ uv.lock लिखता है। आप जोड़ते समय भी पिन कर सकते हैं:

uv add 'requests==2.31.0'

uv.lock को Git में कमिट करें। यह "नवीनतम requests इंस्टॉल करें" (जो समय के साथ बदलता रहता है) और "हमने जिस सटीक ट्री का परीक्षण किया वही इंस्टॉल करें" के बीच का अंतर है। जब आपका एजेंट — या आपका CI, या कोई नया टीममेट — uv sync चलाता है, तो उन्हें बाइट-दर-बाइट समान वातावरण मिलता है।

बिना कुछ सक्रिय किए कोड चलाएं

uv run main.py

uv run यह सुनिश्चित करता है कि वातावरण सिंक में है, फिर उसी के अंदर निष्पादित करता है — कोई source .venv/bin/activate का झंझट नहीं। यह विशेष रूप से एजेंट्स के लिए मायने रखता है: प्रत्येक टूल कॉल अक्सर एक नया शेल होता है, इसलिए "सक्रिय करें फिर चलाएं" बार-बार टूट जाता है, जबकि एक ही uv run हमेशा काम करता है। आप किसी भी कमांड को रैप कर सकते हैं:

uv run -- pytest -q
uv run -- flask run -p 3000

एक Python वर्शन पिन करें ताकि एजेंट और CI सहमत हों

uv python pin 3.12

यह वर्शन को .python-version में लिख देता है, और uv उस इंटरप्रेटर को स्वचालित रूप से डाउनलोड और उपयोग करेगा — किसी सिस्टम Python की आवश्यकता नहीं। अब जिस वर्शन के विरुद्ध आप डेवलप करते हैं, वही वर्शन आपका एजेंट, आपके टीममेट, और आपका CI सभी उपयोग करते हैं।

एक संक्षिप्त उदाहरण

मान लीजिए आप किसी एजेंट से कहते हैं "एक कमांड जोड़ो जो आज का मौसम लाए।" uv के होने पर, पूरा लूप साफ़-सुथरा रहता है:

uv init weather-cli && cd weather-cli
uv add requests
uv python pin 3.12
# एजेंट किसी API को कॉल करने के लिए main.py संपादित करता है...
uv run main.py

एजेंट को कभी यह सोचने की ज़रूरत नहीं होती कि कौन सा इंटरप्रेटर सक्रिय है या requests इंस्टॉल है या नहीं — ये तथ्य उन फ़ाइलों में घोषित हैं जिन्हें वह पढ़ सकता है। अगर वह कोई नई डिपेंडेंसी पेश करता है, तो वह uv add चलाता है और lockfile अपडेट हो जाता है। अगर CI में कुछ टूटता है, तो uv sync सटीक वातावरण को स्थानीय रूप से पुनरुत्पादित कर देता है ताकि आप उसे डिबग कर सकें।

uv किस दिशा में जा रहा है

uv और इसके सहयोगी टूल ruff (लिंटर/फ़ॉर्मेटर) और ty (टाइप चेकर) व्यापक रूप से अपनाए जा रहे हैं — अकेले uv को हर महीने 10 करोड़ से कहीं अधिक डाउनलोड मिलते हैं। मार्च 2026 में, OpenAI ने इनके पीछे की कंपनी Astral को अधिग्रहित करने पर सहमति जताई, ताकि इस टूलचेन को अपने Codex प्लेटफ़ॉर्म में शामिल किया जा सके, साथ ही MIT-लाइसेंस वाले टूल्स को ओपन सोर्स बनाए रखने की प्रतिबद्धता भी जताई (OpenAI, Simon Willison)। फ़िलहाल व्यावहारिक निष्कर्ष अपरिवर्तित है: uv किसी Python प्रोजेक्ट तक पहुंचने का सबसे तेज़ रास्ता है जिस पर आपका AI एजेंट बिना अनुमान लगाए निर्माण कर सकता है।

त्वरित संदर्भ

कार्य	कमांड
प्रोजेक्ट बनाएं	uv init <name>
डिपेंडेंसी जोड़ें	uv add <package>
Python पिन करें	uv python pin 3.12
कोड चलाएं	uv run <file or command>
वातावरण पुनरुत्पादित करें	uv sync
lockfile अपडेट करें	uv lock --upgrade-package <pkg>