Skip to content

Creating projectsプロジェクトを作成する

uv supports creating a project with uv init.uvはuv initを使用してプロジェクトを作成することをサポートしています。

When creating projects, uv supports two basic templates: applications and libraries. By default, uv will create a project for an application. The --lib flag can be used to create a project for a library instead.プロジェクトを作成する際、uvは2つの基本テンプレートをサポートしています: アプリケーションと ライブラリ。デフォルトでは、uvはアプリケーション用のプロジェクトを作成します。--lib フラグを使用すると、ライブラリ用のプロジェクトを作成できます。

Target directoryターゲットディレクトリ

uv will create a project in the working directory, or, in a target directory by providing a name, e.g., uv init foo. The working directory can be modified with the --directory option, which will cause the target directory path will be interpreted relative to the specified working directory. If there's already a project in the target directory, i.e., if there's a pyproject.toml, uv will exit with an error.uvは作業ディレクトリ内にプロジェクトを作成します。また、名前を指定することでターゲットディレクトリに作成することもできます。 e.g., uv init foo。作業ディレクトリは--directoryオプションで変更でき、指定された作業ディレクトリに対してターゲットディレクトリのパスが相対的に解釈されます。ターゲットディレクトリにすでにプロジェクトが存在する場合、すなわちpyproject.tomlが存在する場合、uvはエラーで終了します。

Applicationsアプリケーション

Application projects are suitable for web servers, scripts, and command-line interfaces.アプリケーションプロジェクトは、ウェブサーバー、スクリプト、およびコマンドラインインターフェースに適しています。

Applications are the default target for uv init, but can also be specified with the --app flag.アプリケーションはuv initのデフォルトターゲットですが、--appフラグを使用して指定することもできます。

$ uv init example-app

The project includes a pyproject.toml, a sample file (main.py), a readme, and a Python version pin file (.python-version).プロジェクトには、pyproject.toml、サンプルファイル（main.py）、リードミー、およびPythonバージョンピンファイル（.python-version）が含まれています。

$ tree example-app
example-app
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

Note注意

Prior to v0.6.0, uv created a file named hello.py instead of main.py.v0.6.0以前は、uvはmain.pyの代わりにhello.pyというファイルを作成しました。

The pyproject.toml includes basic metadata. It does not include a build system, it is not a package and will not be installed into the environment:pyproject.tomlには基本的なメタデータが含まれています。ビルドシステムは含まれておらず、これはパッケージではなく、環境にインストールされることはありません：

pyproject.toml
[project]
name = "example-app"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = []

The sample file defines a main function with some standard boilerplate:サンプルファイルは、いくつかの標準的なボイラープレートを持つmain関数を定義しています：

main.py
def main():
    print("Hello from example-app!")


if __name__ == "__main__":
    main()

Python files can be executed with uv run:Pythonファイルはuv runで実行できます：

$ cd example-app
$ uv run main.py
Hello from example-project!

Packaged applicationsパッケージ化されたアプリケーション

Many use-cases require a package. For example, if you are creating a command-line interface that will be published to PyPI or if you want to define tests in a dedicated directory.多くのユースケースではパッケージが必要です。たとえば、PyPIに公開されるコマンドラインインターフェースを作成する場合や、専用のディレクトリにテストを定義したい場合です。

The --package flag can be used to create a packaged application:--packageフラグを使用して、パッケージ化されたアプリケーションを作成できます：

$ uv init --package example-pkg

The source code is moved into a src directory with a module directory and an __init__.py file:ソースコードは、モジュールディレクトリと__init__.pyファイルを持つsrcディレクトリに移動されます：

$ tree example-pkg
example-pkg
├── .python-version
├── README.md
├── pyproject.toml
└── src
    └── example_pkg
        └── __init__.py

A build system is defined, so the project will be installed into the environment:ビルドシステムが定義されているため、プロジェクトは環境にインストールされます：

pyproject.toml
[project]
name = "example-pkg"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = []

[project.scripts]
example-pkg = "example_pkg:main"

[build-system]
requires = ["uv_build>=0.9.13,<0.10.0"]
build-backend = "uv_build"

Tipヒント

The --build-backend option can be used to request an alternative build system.--build-backendオプションは、代替ビルドシステムを要求するために使用できます。

A command definition is included:コマンド定義が含まれています:

pyproject.toml
[project]
name = "example-pkg"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = []

[project.scripts]
example-pkg = "example_pkg:main"

[build-system]
requires = ["uv_build>=0.9.13,<0.10.0"]
build-backend = "uv_build"

The command can be executed with uv run:コマンドはuv runで実行できます:

$ cd example-pkg
$ uv run example-pkg
Hello from example-pkg!

Librariesライブラリ

A library provides functions and objects for other projects to consume. Libraries are intended to be built and distributed, e.g., by uploading them to PyPI.ライブラリは、他のプロジェクトが利用するための関数やオブジェクトを提供します。ライブラリは、例えばPyPIにアップロードすることで、ビルドおよび配布されることを意図しています。

Libraries can be created by using the --lib flag:ライブラリは--libフラグを使用して作成できます:

$ uv init --lib example-lib

Note注意

Using --lib implies --package. Libraries always require a packaged project.--libを使用することは--packageを意味します。ライブラリは常にパッケージ化されたプロジェクトを必要とします。

As with a packaged application, a src layout is used. A py.typed marker is included to indicate to consumers that types can be read from the library:パッケージ化されたアプリケーションと同様に、srcレイアウトが使用されます。py.typedマーカーが含まれており、消費者にライブラリから型を読み取れることを示します:

$ tree example-lib
example-lib
├── .python-version
├── README.md
├── pyproject.toml
└── src
    └── example_lib
        ├── py.typed
        └── __init__.py

Note注意

A src layout is particularly valuable when developing libraries. It ensures that the library is isolated from any python invocations in the project root and that distributed library code is well separated from the rest of the project source.srcレイアウトは、ライブラリを開発する際に特に価値があります。これにより、ライブラリがプロジェクトルートのpython呼び出しから隔離され、配布されたライブラリコードがプロジェクトソースの他の部分から適切に分離されます。

A build system is defined, so the project will be installed into the environment:ビルドシステムが定義されているため、プロジェクトは環境にインストールされます:

pyproject.toml
[project]
name = "example-lib"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = []

[build-system]
requires = ["uv_build>=0.9.13,<0.10.0"]
build-backend = "uv_build"

Tipヒント

You can select a different build backend template by using --build-backend with hatchling, uv_build, flit-core, pdm-backend, setuptools, maturin, or scikit-build-core. An alternative backend is required if you want to create a library with extension modules.異なるビルドバックエンドテンプレートを選択するには、--build-backendを使用してhatchling、uv_build、flit-core、pdm-backend、setuptools、maturin、またはscikit-build-coreを指定します。拡張モジュールを持つライブラリを作成する場合は、代替のバックエンドが必要です。

The created module defines a simple API function:作成されたモジュールは、シンプルなAPI関数を定義します：

__init__.py
def hello() -> str:
    return "Hello from example-lib!"

And you can import and execute it using uv run:そして、uv runを使用してインポートして実行できます：

$ cd example-lib
$ uv run python -c "import example_lib; print(example_lib.hello())"
Hello from example-lib!

Projects with extension modules拡張モジュールを持つプロジェクト

Most Python projects are "pure Python", meaning they do not define modules in other languages like C, C++, FORTRAN, or Rust. However, projects with extension modules are often used for performance sensitive code.ほとんどのPythonプロジェクトは「純粋なPython」であり、C、C++、FORTRAN、またはRustのような他の言語でモジュールを定義しません。しかし、拡張モジュールを持つプロジェクトは、パフォーマンスに敏感なコードのためによく使用されます。

Creating a project with an extension module requires choosing an alternative build system. uv supports creating projects with the following build systems that support building extension modules:拡張モジュールを持つプロジェクトを作成するには、代替のビルドシステムを選択する必要があります。uvは、拡張モジュールのビルドをサポートする以下のビルドシステムを使用してプロジェクトを作成することをサポートしています：

Specify the build system with the --build-backend flag:--build-backendフラグでビルドシステムを指定します：

$ uv init --build-backend maturin example-ext

Note注意

Using --build-backend implies --package.--build-backendを使用すると、--packageが暗黙的に含まれます。

The project contains a Cargo.toml and a lib.rs file in addition to the typical Python project files:プロジェクトには、典型的なPythonプロジェクトファイルに加えて、Cargo.tomlとlib.rsファイルが含まれています。

$ tree example-ext
example-ext
├── .python-version
├── Cargo.toml
├── README.md
├── pyproject.toml
└── src
    ├── lib.rs
    └── example_ext
        ├── __init__.py
        └── _core.pyi

Note注意

If using scikit-build-core, you'll see CMake configuration and a main.cpp file instead.scikit-build-coreを使用している場合、CMakeの設定とmain.cppファイルが表示されます。

The Rust library defines a simple function:Rustライブラリはシンプルな関数を定義しています：

src/lib.rs
use pyo3::prelude::*;

#[pymodule]
mod _core {
    use pyo3::prelude::*;

    #[pyfunction]
    fn hello_from_bin() -> String {
        "Hello from example-ext!".to_string()
    }
}

And the Python module imports it:そしてPythonモジュールはそれをインポートします：

src/example_ext/__init__.py
from example_ext._core import hello_from_bin


def main() -> None:
    print(hello_from_bin())

The command can be executed with uv run:コマンドはuv runで実行できます：

$ cd example-ext
$ uv run example-ext
Hello from example-ext!

Important重要

When creating a project with maturin or scikit-build-core, uv configures tool.uv.cache-keys to include common source file types. To force a rebuild, e.g. when changing files outside cache-keys or when not using cache-keys, use --reinstall.maturinまたはscikit-build-coreを使用してプロジェクトを作成する際、uvはtool.uv.cache-keysを設定し、一般的なソースファイルタイプを含めます。再ビルドを強制するには、例えばcache-keysの外でファイルを変更した場合やcache-keysを使用していない場合は、--reinstallを使用してください。

Creating a minimal project最小限のプロジェクトを作成する

If you only want to create a pyproject.toml, use the --bare option:pyproject.tomlのみを作成したい場合は、--bareオプションを使用してください：

$ uv init example --bare

uv will skip creating a Python version pin file, a README, and any source directories or files. Additionally, uv will not initialize a version control system (i.e., git).uvはPythonバージョンピンファイル、README、およびソースディレクトリやファイルの作成をスキップします。さらに、uvはバージョン管理システム（つまり、git）を初期化しません。

$ tree example-bare
example-bare
└── pyproject.toml

uv will also not add extra metadata to the pyproject.toml, such as the description or authors.uvはまた、pyproject.tomlにdescriptionやauthorsなどの追加メタデータを追加しません。

[project]
name = "example"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = []

The --bare option can be used with other options like --lib or --build-backend — in these cases uv will still configure a build system but will not create the expected file structure.--bare オプションは、--lib や --build-backend のような他のオプションと一緒に使用できます — この場合、uv は依然としてビルドシステムを構成しますが、期待されるファイル構造は作成しません。

When --bare is used, additional features can still be used opt-in:--bare が使用されると、追加機能はオプトインで引き続き使用できます:

$ uv init example --bare --description "Hello world" --author-from git --vcs git --python-pin