Astral製uvとtyでPythonワークフローを再設計する

uv と ty を導入する理由

• pip + virtualenv + pip-tools を組み合わせた従来構成より、uvは依存解決・ビルド・実行を一体化し高速。
• プロジェクトルートが多くても uv tool run で即座にCLIを呼び出せるため、CI/CDでも再現性が高い。
• tyはシェルスクリプトを型安全に記述でき、Python/Node/Goなど異なるツールチェーンを統一したコマンドで呼び出せる。
• Astral製ツールはモノリポやLLMパイプラインなど、規模が大きいプロジェクトでも乱雑になりがちなMakefileやpipenvを置き換えられる。

uv の基本セットアップ

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

~/.local/bin にインストールされるので、PATHを通す。uv --version で確認。

プロジェクト初期化

uv init my-app
cd my-app
uv add fastapi uvicorn[standard]

uv init は仮想環境と pyproject.toml をまとめて生成。uv add は解決した依存を uv.lock に書き込み、uv pip sync で再現可能。

スクリプトの実行とタスク管理

# pyproject.toml
[tool.uv.scripts]
lint = "ruff check ."
serve = "fastapi dev app.py"

uv run lint
uv run serve

uv run は仮想環境作成不要でスクリプトを実行。CIでは uv python で指定バージョンのPythonを取得できる。

uvx でCLIを即利用

uvx ruff check src/
uvx mypy src/

uvx はnpm npxのようなワンショット実行。ローカルにインストールせず最新バージョンを取得し、多数の補助ツールを気軽に呼び出せる。

ty でコマンドランナーを型安全に

tyはTypeScript風の構文でシェルタスクを記述し、環境変数/依存ツールを明示的に宣言できる。

インストール

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

基本的な ty ファイル

// ty.ts
import { task, exec } from 'ty'</pre>

task('lint', async () => {
  await exec`uvx ruff check src/`;
  await exec`uvx mypy src/`;
});

task('serve', async () => {
  await exec`uv run fastapi dev app.py`;
});

export const defaultTask = 'lint';

実行:

ty lint

TypeScriptベースなので、エディタ補完や型チェックでコマンド間違いを防げる。task('deploy', { env: { ENV: 'prod' } }, ...) のように環境変数も型安全に設定可能。

並列実行と依存関係

task('test', async ({ run }) => {
  await run(['fmt', 'lint']);
});

run に配列を渡すと並列、await run('lint') で逐次実行。複雑なCIパイプラインを簡潔にモデル化できる。

uv + ty の組み合わせ

1. uv でPython依存を固定、uvx でToolingを呼び出す。
2. ty のタスクから uv run や uvx を呼ぶことで、チーム全員が同じCLIを利用する。

例: ドキュメント生成＋テスト＋デプロイを一気通貫で管理。

task('docs', async () => {
  await exec`uv run mkdocs build`;
});

task('e2e', async () => {
  await exec`uv run pytest tests/e2e -n auto`;
});

export const defaultTask = 'docs';

CI/CD への適用例

name: ci
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v1
      - uses: astral-sh/setup-ty@v1
      - run: ty lint
      - run: ty e2e

GitHub Actionsで公式アクションを使えば、環境準備は数秒。uv lockをキャッシュして再現性を高める。

運用ベストプラクティス

• uv.lockをリポジトリにコミットし、依存を固定。
• ty ファイルでタスク名を明確にし、READMEに一覧を載せる。
• 開発者マシンでもCIでも同じtyコマンドを叩けば動く状態を保つ。
• LLMやデータパイプラインの補助CLI（sqlfluff, duckdb, langchain-cliなど）は uvx でその場実行し、ごみが残らない構成にする。

まとめ

Astralのuvとtyを導入すると、Pythonプロジェクトの依存管理とタスク実行を一貫したインターフェースで扱えます。特にLLMやデータ系プロジェクトではCLIの乱立や仮想環境の重複が生産性を下げる原因になりがちです。まずはuv initとtyファイルをプロジェクトに追加し、uvxで補助ツールを呼び出すワークフローに切り替えてみてください。