Migrating from pip to a uv projectpipからuvプロジェクトへの移行
This guide will discuss converting from a pip and pip-tools workflow centered on requirements
files to uv's project workflow using a pyproject.toml and uv.lock file.このガイドでは、requirementsファイルを中心としたpipおよびpip-toolsのワークフローから、pyproject.tomlおよびuv.lockファイルを使用したuvのプロジェクトワークフローへの変換について説明します。
Note注意
If you're looking to migrate from pip and pip-tools to uv's drop-in interface or from an
existing workflow where you're already using a pyproject.toml, those guides are not yet
written. See #5200 to track progress.もしpipおよびpip-toolsからuvのドロップインインターフェースへの移行や、すでにpyproject.tomlを使用している既存のワークフローからの移行を考えている場合、それらのガイドはまだ作成されていません。進捗を追跡するには#5200を参照してください。
We'll start with an overview of developing with pip, then discuss migrating to uv.まず、pipを使用した開発の概要を説明し、その後uvへの移行について説明します。
Tipヒント
If you're familiar with the ecosystem, you can jump ahead to the requirements file import instructions.エコシステムに精通している場合は、 requirementsファイルのインポート手順に飛ぶことができます。
Understanding pip workflowspipワークフローの理解
Project dependenciesプロジェクトの依存関係
When you want to use a package in your project, you need to install it first. pip supports
imperative installation of packages, e.g.:プロジェクトでパッケージを使用したい場合は、まずそれをインストールする必要があります。 pip は
パッケージの命令的インストールをサポートしています。例えば:
This installs the package into the environment that pip is installed in. This may be a virtual
environment, or, the global environment of your system's Python installation.これにより、pip がインストールされている環境にパッケージがインストールされます。これは仮想環境であるか、システムのPythonインストールのグローバル環境である可能性があります。
Then, you can run a Python script that requires the package:次に、そのパッケージを必要とするPythonスクリプトを実行できます:
It's best practice to create a virtual environment for each project, to avoid mixing packages between them. For example:パッケージが混在しないように、各プロジェクトのために仮想環境を作成することがベストプラクティスです。例えば:
We will revisit this topic in the project environments section below.このトピックは、下記のプロジェクト環境セクションで再訪します。
Requirements files要件ファイル
When sharing projects with others, it's useful to declare all the packages you require upfront.
pip supports installing requirements from a file, e.g.:他の人とプロジェクトを共有する際には、必要なすべてのパッケージを事前に宣言することが便利です。
pip はファイルからの要件のインストールをサポートしています。例えば:
Notice above that fastapi is not "locked" to a specific version — each person working on the
project may have a different version of fastapi installed. pip-tools was created to improve this
experience.上記のように、fastapi は特定のバージョンに「ロック」されていないことに注意してください — プロジェクトに関わる各人が異なるバージョンのfastapiをインストールしている可能性があります。 pip-tools はこの体験を改善するために作成されました。
When using pip-tools, requirements files specify both the dependencies for your project and lock
dependencies to a specific version — the file extension is used to differentiate between the two.
For example, if you require fastapi and pydantic, you'd specify these in a requirements.in
file:pip-tools を使用する際、要件ファイルはプロジェクトの依存関係を指定し、依存関係を特定のバージョンにロックします — ファイル拡張子は両者を区別するために使用されます。
例えば、fastapi と pydantic が必要な場合、これらを requirements.in ファイルに指定します:
Notice there's a version constraint on pydantic — this means only pydantic versions later than
2.0.0 can be used. In contrast, fastapi does not have a version constraint — any version can be
used.pydanticにはバージョン制約があることに注意してください。これは、2.0.0以降のpydanticバージョンのみが使用できることを意味します。それに対して、fastapiにはバージョン制約がなく、任意のバージョンを使用できます。
These dependencies can be compiled into a requirements.txt file:これらの依存関係はrequirements.txtファイルにコンパイルできます：
annotated-types==0.7.0
# via pydantic
anyio==4.8.0
# via starlette
fastapi==0.115.11
# via -r requirements.in
idna==3.10
# via anyio
pydantic==2.10.6
# via
# -r requirements.in
# fastapi
pydantic-core==2.27.2
# via pydantic
sniffio==1.3.1
# via anyio
starlette==0.46.1
# via fastapi
typing-extensions==4.12.2
# via
# fastapi
# pydantic
# pydantic-core
Here, all the versions constraints are exact. Only a single version of each package can be used.
The above example was generated with uv pip compile, but could also be generated with
pip-compile from pip-tools.ここでは、すべてのバージョン制約が正確です。各パッケージの単一のバージョンのみが使用できます。上記の例はuv pip compileで生成されましたが、pip-toolsのpip-compileを使用して生成することもできます。
Though less common, the requirements.txt can also be generated using pip freeze, by first
installing the input dependencies into the environment then exporting the installed versions:あまり一般的ではありませんが、requirements.txtはpip freezeを使用して生成することもできます。最初に入力依存関係を環境にインストールし、その後インストールされたバージョンをエクスポートします：
annotated-types==0.7.0
anyio==4.8.0
fastapi==0.115.11
idna==3.10
pydantic==2.10.6
pydantic-core==2.27.2
sniffio==1.3.1
starlette==0.46.1
typing-extensions==4.12.2
After compiling dependencies into a locked set of versions, these files are committed to version control and distributed with the project.依存関係をロックされたバージョンセットにコンパイルした後、これらのファイルはバージョン管理にコミットされ、プロジェクトと共に配布されます。
Then, when someone wants to use the project, they install from the requirements file:その後、誰かがプロジェクトを使用したい場合、彼らはrequirementsファイルからインストールします：
Development dependencies開発依存関係
The requirements file format can only describe a single set of dependencies at once. This means if
you have additional groups of dependencies, such as development dependencies, they need separate
files. For example, we'll create a -dev dependency file:requirementsファイル形式は、一度に単一の依存関係セットのみを記述できます。これは、開発依存関係などの追加のグループの依存関係がある場合、それらは別のファイルが必要であることを意味します。例えば、-dev依存関係ファイルを作成します：
Notice the base requirements are included with -r requirements.in. This ensures your development
environment considers all of the dependencies together. The -c requirements.txt constrains the
package version to ensure that the requirements-dev.txt uses the same versions as
requirements.txt.基本要件が-r requirements.inで含まれていることに注意してください。これにより、開発環境はすべての依存関係を一緒に考慮します。-c requirements.txtはパッケージバージョンを制約し、requirements-dev.txtがrequirements.txtと同じバージョンを使用することを保証します。
Note注意
It's common to use -r requirements.txt directly instead of using both
-r requirements.in, and -c requirements.txt. There's no difference in the resulting package
versions, but using both files produces annotations which allow you to determine which
dependencies are direct (annotated with -r requirements.in) and which are indirect (only
annotated with -c requirements.txt).-r requirements.txtを直接使用することが一般的であり、-r requirements.inと-c requirements.txtの両方を使用する必要はありません。結果として得られるパッケージバージョンには違いはありませんが、両方のファイルを使用すると、どの依存関係が直接（-r requirements.inで注釈付き）で、どの依存関係が間接（-c requirements.txtでのみ注釈付き）であるかを判断できる注釈が生成されます。
The compiled development dependencies look like:コンパイルされた開発依存関係は次のようになります：
annotated-types==0.7.0
# via
# -c requirements.txt
# pydantic
anyio==4.8.0
# via
# -c requirements.txt
# starlette
fastapi==0.115.11
# via
# -c requirements.txt
# -r requirements.in
idna==3.10
# via
# -c requirements.txt
# anyio
iniconfig==2.0.0
# via pytest
packaging==24.2
# via pytest
pluggy==1.5.0
# via pytest
pydantic==2.10.6
# via
# -c requirements.txt
# -r requirements.in
# fastapi
pydantic-core==2.27.2
# via
# -c requirements.txt
# pydantic
pytest==8.3.5
# via -r requirements-dev.in
sniffio==1.3.1
# via
# -c requirements.txt
# anyio
starlette==0.46.1
# via
# -c requirements.txt
# fastapi
typing-extensions==4.12.2
# via
# -c requirements.txt
# fastapi
# pydantic
# pydantic-core
As with the base dependency files, these are committed to version control and distributed with the project. When someone wants to work on the project, they'll install from the requirements file:基本依存ファイルと同様に、これらはバージョン管理にコミットされ、プロジェクトと共に配布されます。誰かがプロジェクトに取り組みたい場合、彼らはrequirementsファイルからインストールします:
Platform-specific dependenciesプラットフォーム固有の依存関係
When compiling dependencies with pip or pip-tools, the result is only usable on the same
platform as it is generated on. This poses a problem for projects which need to be usable on
multiple platforms, such as Windows and macOS.pipやpip-toolsを使用して依存関係をコンパイルする際、結果は生成された同じプラットフォームでのみ使用可能です。これは、WindowsやmacOSなど、複数のプラットフォームで使用可能である必要があるプロジェクトにとって問題を引き起こします。
For example, take a simple dependency:例えば、シンプルな依存関係を考えてみましょう:
On Linux, this compiles to:Linuxでは、これがコンパイルされます:
While on Windows, this compiles to:一方、Windowsでは、これがコンパイルされます:
colorama is a Windows-only dependency of tqdm.coloramaはtqdmのWindows専用依存関係です。
When using pip and pip-tools, a project needs to declare a requirements lock file for each
supported platform.pipとpip-toolsを使用する際、プロジェクトはサポートされている各プラットフォームのためにrequirementsロックファイルを宣言する必要があります。
Note注意
uv's resolver can compile dependencies for multiple platforms at once (see "universal resolution"),
allowing you to use a single requirements.txt for all platforms:uvのリゾルバは、複数のプラットフォームの依存関係を同時にコンパイルできます（「ユニバーサルリゾリューション」を参照）、これによりすべてのプラットフォームで単一のrequirements.txtを使用できます:
colorama==0.4.6 ; sys_platform == 'win32'
# via tqdm
tqdm==4.67.1
# via -r requirements.in
This resolution mode is also used when using a pyproject.toml and uv.lock.このリゾリューションモードは、pyproject.tomlとuv.lockを使用する際にも使用されます。
Migrating to a uv projectuvプロジェクトへの移行
The pyproject.tomlpyproject.tomlの
The pyproject.toml is a standardized file for Python project metadata. It replaces
requirements.in files, allowing you to represent arbitrary groups of project dependencies. It also
provides a centralized location for metadata about your project, such as the build system or tool
settings.pyproject.tomlはPythonプロジェクトのメタデータのための標準化されたファイルです。これは
requirements.inファイルに取って代わり、プロジェクト依存関係の任意のグループを表現することを可能にします。また、ビルドシステムやツール設定など、プロジェクトに関するメタデータの中央集約された場所を提供します。
For example, the requirements.in and requirements-dev.in files above can be translated to a
pyproject.toml as follows:例えば、上記のrequirements.inおよびrequirements-dev.inファイルは、次のようにpyproject.tomlに変換できます：
[project]
name = "example"
version = "0.0.1"
dependencies = [
"fastapi",
"pydantic>2"
]
[dependency-groups]
dev = ["pytest"]
We'll discuss the commands necessary to automate these imports below.これらのインポートを自動化するために必要なコマンドについては、以下で説明します。
The uv lockfileuvロックファイル
uv uses a lockfile (uv.lock) file to lock package versions. The format of this file is specific to
uv, allowing uv to support advanced features. It replaces requirements.txt files.uvはパッケージのバージョンを固定するためにロックファイル（uv.lock）を使用します。このファイルの形式はuv特有であり、uvが高度な機能をサポートできるようにします。これはrequirements.txtファイルに取って代わります。
The lockfile will be automatically created and populated when adding dependencies, but you can
explicitly create it with uv lock.ロックファイルは依存関係を追加する際に自動的に作成され、 populated されますが、uv lockを使用して明示的に作成することもできます。
Unlike requirements.txt files, the uv.lock file can represent arbitrary groups of dependencies,
so multiple files are not needed to lock development dependencies.requirements.txtファイルとは異なり、uv.lockファイルは任意の依存関係のグループを表現できるため、開発依存関係をロックするために複数のファイルは必要ありません。
The uv lockfile is always universal, so multiple files are not needed to lock dependencies for each platform. This ensures that all developers are using consistent, locked versions of dependencies regardless of their machine.uvロックファイルは常にユニバーサルであるため、各プラットフォームの依存関係をロックするために複数のファイルは必要ありません。これにより、すべての開発者が自分のマシンに関係なく、一貫したロックされた依存関係のバージョンを使用していることが保証されます。
The uv lockfile also supports concepts like
pinning packages to specific indexes,
which is not representable in requirements.txt files.uvロックファイルはまた、特定のインデックスにパッケージをピン留めするなどの概念をサポートしており、これはrequirements.txtファイルでは表現できません。
Tipヒント
If you only need to lock for a subset of platforms, use the
tool.uv.environments setting
to limit the resolution and lockfile.特定のプラットフォームのサブセットのためだけにロックする必要がある場合は、tool.uv.environments設定を使用して、解決とロックファイルを制限してください。
To learn more, see the lockfile documentation.詳細については、lockfile ドキュメントを参照してください。
Importing requirements files要件ファイルのインポート
First, create a pyproject.toml if you have not already:まず、まだ作成していない場合は pyproject.toml を作成してください:
Then, the easiest way to import requirements is with uv add:次に、要件をインポートする最も簡単な方法は uv add を使用することです:
However, there is some nuance to this transition. Notice we used the requirements.in file, which
does not pin to exact versions of packages so uv will solve for new versions of these packages. You
may want to continue using your previously locked versions from your requirements.txt so, when
switching over to uv, none of your dependency versions change.ただし、この移行にはいくつかのニュアンスがあります。requirements.in ファイルを使用したことに注意してください。これはパッケージの正確なバージョンを固定しないため、uv はこれらのパッケージの新しいバージョンを解決します。requirements.txt から以前にロックされたバージョンを引き続き使用したい場合は、uv に切り替えるときに依存関係のバージョンが変更されないようにしてください。
The solution is to add your locked versions as constraints. uv supports using these on add to
preserve locked versions:解決策は、ロックされたバージョンを 制約 として追加することです。uv は、ロックされたバージョンを保持するために add でこれを使用することをサポートしています:
Your existing versions will be retained when producing a uv.lock file.既存のバージョンは uv.lock ファイルを生成する際に保持されます。
Importing platform-specific constraintsプラットフォーム固有の制約のインポート
If your platform-specific dependencies have been compiled into separate files, you can still
transition to a universal lockfile. However, you cannot just use -c to specify constraints from
your existing platform-specific requirements.txt files because they do not include markers
describing the environment and will consequently conflict.プラットフォーム固有の依存関係が別々のファイルにコンパイルされている場合でも、ユニバーサルロックファイルに移行することができます。ただし、既存のプラットフォーム固有の requirements.txt ファイルから制約を指定するために -c を使用することはできません。なぜなら、それらには環境を説明するマーカーが含まれておらず、結果として競合するからです。
To add the necessary markers, use uv pip compile to convert your existing files. For example,
given the following:必要なマーカーを追加するには、uv pip compile を使用して既存のファイルを変換します。例えば、次のように:
The markers can be added with:マーカーは次のように追加できます：
$ uv pip compile requirements.in -o requirements-win.txt --python-platform windows --no-strip-markers
Notice the resulting output includes a Windows marker on colorama:結果の出力には、coloramaのWindowsマーカーが含まれていることに注意してください：
colorama==0.4.6 ; sys_platform == 'win32'
# via tqdm
tqdm==4.67.1
# via -r requirements.in
When using -o, uv will constrain the versions to match the existing output file, if it can.-oを使用すると、uvは既存の出力ファイルに一致するようにバージョンを制約します。
Markers can be added for other platforms by changing the --python-platform and -o values for
each requirements file you need to import, e.g., to linux and macos.他のプラットフォーム用のマーカーは、各要件ファイルをインポートするために--python-platformと-oの値を変更することで追加できます。例えば、linuxやmacosに変更します。
Once each requirements.txt file has been transformed, the dependencies can be imported to the
pyproject.toml and uv.lock with uv add:各requirements.txtファイルが変換されたら、依存関係をpyproject.tomlとuv.lockにuv addでインポートできます：
Importing development dependency files開発依存ファイルのインポート
As discussed in the development dependencies section, it's common to have groups of dependencies for development purposes.開発依存関係のセクションで説明したように、開発目的のために依存関係のグループを持つことは一般的です。
To import development dependencies, use the --dev flag during uv add:開発依存関係をインポートするには、uv addの際に--devフラグを使用します：
If the requirements-dev.in includes the parent requirements.in via -r, it will need to be
stripped to avoid adding the base requirements to the dev dependency group. The following example
uses sed to strip lines that start with -r, then pipes the result to uv add:requirements-dev.inが-rを介して親のrequirements.inを含む場合、dev依存関係グループに基本要件を追加しないように削除する必要があります。以下の例では、sedを使用して-rで始まる行を削除し、その結果をuv addにパイプします：
In addition to the dev dependency group, uv supports arbitrary group names. For example, if you
also have a dedicated set of dependencies for building your documentation, those can be imported to
a docs group:dev依存関係グループに加えて、uvは任意のグループ名をサポートしています。例えば、ドキュメントを構築するための専用の依存関係セットがある場合、それらをdocsグループにインポートできます：
Project environmentsプロジェクト環境
Unlike pip, uv is not centered around the concept of an "active" virtual environment. Instead, uv
uses a dedicated virtual environment for each project in a .venv directory. This environment is
automatically managed, so when you run a command, like uv add, the environment is synced with the
project dependencies.pipとは異なり、uvは「アクティブ」な仮想環境の概念に基づいていません。代わりに、uvは各プロジェクトのために.venvディレクトリ内に専用の仮想環境を使用します。この環境は自動的に管理されるため、uv addのようなコマンドを実行すると、環境がプロジェクトの依存関係と同期されます。
The preferred way to execute commands in the environment is with uv run, e.g.:環境内でコマンドを実行するための推奨方法はuv runを使用することです。例えば：
Prior to every uv run invocation, uv will verify that the lockfile is up-to-date with the
pyproject.toml, and that the environment is up-to-date with the lockfile, keeping your project
in-sync without the need for manual intervention. uv run guarantees that your command is run in a
consistent, locked environment.uv runを呼び出す前に、uvはロックファイルがpyproject.tomlと最新であること、そして環境がロックファイルと最新であることを確認し、手動での介入なしにプロジェクトを同期させます。uv runは、コマンドが一貫したロックされた環境で実行されることを保証します。
The project environment can also be explicitly created with uv sync, e.g., for use with editors.プロジェクト環境はuv syncを使用して明示的に作成することもできます。例えば、エディタで使用するために。
Note注意
When in projects, uv will prefer a .venv in the project directory and ignore the active
environment as declared by the VIRTUAL_ENV variable by default. You can opt-in to using the
active environment with the --active flag.プロジェクト内では、uvはデフォルトでプロジェクトディレクトリ内の.venvを優先し、VIRTUAL_ENV変数によって宣言されたアクティブな環境を無視します。--activeフラグを使用することで、アクティブな環境を使用することを選択できます。
To learn more, see the project environment documentation.詳細については、プロジェクト環境のドキュメントを参照してください。
Next steps次のステップ
Now that you've migrated to uv, take a look at the project concept page for more details about uv projects.uvに移行した今、uvプロジェクトに関する詳細はプロジェクト概念ページを確認してください。