`python.uvConfig` Submodule

Structs

BuildBackendSettings

Settings for the uv build backend (uv_build).

Note that those settings only apply when using the uv_build backend, other build backends (such as hatchling) have their own configuration.

All options that accept globs use the portable glob patterns from PEP 639.

Initializer

import { python } from 'projen'

const buildBackendSettings: python.uvConfig.BuildBackendSettings = { ... }

Properties

Name	Type	Description
`data`	`projen.python.uvConfig.WheelDataIncludes`	Data includes for wheels.
`defaultExcludes`	`boolean`	If set to `false`, the default excludes aren't applied.
`moduleName`	`any`	The name of the module directory inside `module-root`.
`moduleRoot`	`string`	The directory that contains the module directory.
`namespace`	`boolean`	Build a namespace package.
`sourceExclude`	`string[]`	Glob expressions which files and directories to exclude from the source distribution.
`sourceInclude`	`string[]`	Glob expressions which files and directories to additionally include in the source distribution.
`wheelExclude`	`string[]`	Glob expressions which files and directories to exclude from the wheel.

`data`^Optional

public readonly data: WheelDataIncludes;

Type: projen.python.uvConfig.WheelDataIncludes

Data includes for wheels.

Each entry is a directory, whose contents are copied to the matching directory in the wheel in <name>-<version>.data/(purelib|platlib|headers|scripts|data). Upon installation, this data is moved to its target location, as defined by https://docs.python.org/3.12/library/sysconfig.html#installation-paths. Usually, small data files are included by placing them in the Python module instead of using data includes.

scripts: Installed to the directory for executables, <venv>/bin on Unix or <venv>\Scripts on Windows. This directory is added to PATH when the virtual environment is activated or when using uv run, so this data type can be used to install additional binaries. Consider using project.scripts instead for Python entrypoints.
data: Installed over the virtualenv environment root.

Warning: This may override existing files!

headers: Installed to the include directory. Compilers building Python packages with this package as build requirement use the include directory to find additional header files.
purelib and platlib: Installed to the site-packages directory. It is not recommended to use these two options.

`defaultExcludes`^Optional

public readonly defaultExcludes: boolean;

Type: boolean

If set to false, the default excludes aren't applied.

Default excludes: __pycache__, *.pyc, and *.pyo.

`moduleName`^Optional

public readonly moduleName: any;

Type: any

The name of the module directory inside module-root.

The default module name is the package name with dots and dashes replaced by underscores.

Package names need to be valid Python identifiers, and the directory needs to contain a __init__.py. An exception are stubs packages, whose name ends with -stubs, with the stem being the module name, and which contain a __init__.pyi file.

For namespace packages with a single module, the path can be dotted, e.g., foo.bar or foo-stubs.bar.

For namespace packages with multiple modules, the path can be a list, e.g., ["foo", "bar"]. We recommend using a single module per package, splitting multiple packages into a workspace.

Note that using this option runs the risk of creating two packages with different names but the same module names. Installing such packages together leads to unspecified behavior, often with corrupted files or directory trees.

`moduleRoot`^Optional

public readonly moduleRoot: string;

Type: string

The directory that contains the module directory.

Common values are src (src layout, the default) or an empty path (flat layout).

`namespace`^Optional

public readonly namespace: boolean;

Type: boolean

Build a namespace package.

Build a PEP 420 implicit namespace package, allowing more than one root __init__.py.

Use this option when the namespace package contains multiple root __init__.py, for namespace packages with a single root __init__.py use a dotted module-name instead.

To compare dotted module-name and namespace = true, the first example below can be expressed with module-name = "cloud.database": There is one root __init__.py database. In the second example, we have three roots (cloud.database, cloud.database_pro, billing.modules.database_pro), so namespace = true is required.

src
└── cloud
└── database
├── __init__.py
├── query_builder
│   └── __init__.py
└── sql
├── parser.py
└── __init__.py

src
├── cloud
│   ├── database
│   │   ├── __init__.py
│   │   ├── query_builder
│   │   │   └── __init__.py
│   │   └── sql
│   │       ├── __init__.py
│   │       └── parser.py
│   └── database_pro
│       ├── __init__.py
│       └── query_builder.py
└── billing
└── modules
└── database_pro
├── __init__.py
└── sql.py

`sourceExclude`^Optional

public readonly sourceExclude: string[];

Type: string[]

Glob expressions which files and directories to exclude from the source distribution.

`sourceInclude`^Optional

public readonly sourceInclude: string[];

Type: string[]

Glob expressions which files and directories to additionally include in the source distribution.

pyproject.toml and the contents of the module directory are always included.

`wheelExclude`^Optional

public readonly wheelExclude: string[];

Type: string[]

Glob expressions which files and directories to exclude from the wheel.

DependencyGroupSettings

Initializer

import { python } from 'projen'

const dependencyGroupSettings: python.uvConfig.DependencyGroupSettings = { ... }

Properties

Name	Type	Description
`requiresPython`	`string`	Version of python to require when installing this group.

`requiresPython`^Optional

public readonly requiresPython: string;

Type: string

Version of python to require when installing this group.

Index

Initializer

import { python } from 'projen'

const index: python.uvConfig.Index = { ... }

Properties

Name	Type	Description
`url`	`string`	The URL of the index.
`authenticate`	`string`	When uv should use authentication for requests to the index.
`cacheControl`	`projen.python.uvConfig.IndexCacheControl`	Cache control configuration for this index.
`default`	`boolean`	Mark the index as the default index.
`explicit`	`boolean`	Mark the index as explicit.
`format`	`string`	The format used by the index.
`ignoreErrorCodes`	`number[]`	Status codes that uv should ignore when deciding whether to continue searching in the next index after a failure.
`name`	`string`	The name of the index.
`publishUrl`	`string`	The URL of the upload endpoint.

`url`^Required

public readonly url: string;

Type: string

The URL of the index.

Expects to receive a URL (e.g., https://pypi.org/simple) or a local path.

`authenticate`^Optional

public readonly authenticate: string;

Type: string

When uv should use authentication for requests to the index.

[[tool.uv.index]]
name = "my-index"
url = "https://<omitted>/simple"
authenticate = "always"

`cacheControl`^Optional

public readonly cacheControl: IndexCacheControl;

Type: projen.python.uvConfig.IndexCacheControl

Cache control configuration for this index.

When set, these headers will override the server's cache control headers for both package metadata requests and artifact downloads.

[[tool.uv.index]]
name = "my-index"
url = "https://<omitted>/simple"
cache-control = { api = "max-age=600", files = "max-age=3600" }

`default`^Optional

public readonly default: boolean;

Type: boolean

Mark the index as the default index.

By default, uv uses PyPI as the default index, such that even if additional indexes are defined via [[tool.uv.index]], PyPI will still be used as a fallback for packages that aren't found elsewhere. To disable the PyPI default, set default = true on at least one other index.

Marking an index as default will move it to the front of the list of indexes, such that it is given the highest priority when resolving packages.

`explicit`^Optional

public readonly explicit: boolean;

Type: boolean

Mark the index as explicit.

Explicit indexes will only be used when explicitly requested via a [tool.uv.sources] definition, as in:

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu121"
explicit = true

[tool.uv.sources]
torch = { index = "pytorch" }

`format`^Optional

public readonly format: string;

Type: string

The format used by the index.

Indexes can either be PEP 503-compliant (i.e., a PyPI-style registry implementing the Simple API) or structured as a flat list of distributions (e.g., --find-links). In both cases, indexes can point to either local or remote resources.

`ignoreErrorCodes`^Optional

public readonly ignoreErrorCodes: number[];

Type: number[]

Status codes that uv should ignore when deciding whether to continue searching in the next index after a failure.

[[tool.uv.index]]
name = "my-index"
url = "https://<omitted>/simple"
ignore-error-codes = [401, 403]

`name`^Optional

public readonly name: string;

Type: string

The name of the index.

Index names can be used to reference indexes elsewhere in the configuration. For example, you can pin a package to a specific index by name:

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu121"

[tool.uv.sources]
torch = { index = "pytorch" }

`publishUrl`^Optional

public readonly publishUrl: string;

Type: string

The URL of the upload endpoint.

When using uv publish --index <name>, this URL is used for publishing.

A configuration for the default index PyPI would look as follows:

[[tool.uv.index]]
name = "pypi"
url = "https://pypi.org/simple"
publish-url = "https://upload.pypi.org/legacy/"

IndexCacheControl

Cache control configuration for an index.

Initializer

import { python } from 'projen'

const indexCacheControl: python.uvConfig.IndexCacheControl = { ... }

Properties

Name	Type	Description
`api`	`string`	Cache control header for Simple API requests.
`files`	`string`	Cache control header for file downloads.

`api`^Optional

public readonly api: string;

Type: string

Cache control header for Simple API requests.

`files`^Optional

public readonly files: string;

Type: string

Cache control header for file downloads.

PipGroupName

The pip-compatible variant of a [GroupName].

Either or :. If is omitted it defaults to "pyproject.toml".

Initializer

import { python } from 'projen'

const pipGroupName: python.uvConfig.PipGroupName = { ... }

Properties

Name	Type	Description
`name`	`string`	No description.
`path`	`string`	No description.

`name`^Required

public readonly name: string;

Type: string

`path`^Optional

public readonly path: string;

Type: string

PipOptions

Settings that are specific to the uv pip command-line interface.

These values will be ignored when running commands outside the uv pip namespace (e.g., uv lock, uvx).

Initializer

import { python } from 'projen'

const pipOptions: python.uvConfig.PipOptions = { ... }

Properties

Name	Type	Description
`allExtras`	`boolean`	Include all optional dependencies.
`allowEmptyRequirements`	`boolean`	Allow `uv pip sync` with empty requirements, which will clear the environment of all packages.
`annotationStyle`	`string`	The style of the annotation comments included in the output file, used to indicate the source of each package.
`breakSystemPackages`	`boolean`	Allow uv to modify an `EXTERNALLY-MANAGED` Python installation.
`compileBytecode`	`boolean`	Compile Python files to bytecode after installation.
`configSettings`	`{[ key: string ]: any}`	Settings to pass to the PEP 517 build backend, specified as `KEY=VALUE` pairs.
`configSettingsPackage`	`{[ key: string ]: {[ key: string ]: any}}`	Settings to pass to the PEP 517 build backend for specific packages, specified as `KEY=VALUE` pairs.
`customCompileCommand`	`string`	The header comment to include at the top of the output file generated by `uv pip compile`.
`dependencyMetadata`	`projen.python.uvConfig.StaticMetadata[]`	Pre-defined static metadata for dependencies of the project (direct or transitive).
`emitBuildOptions`	`boolean`	Include `--no-binary` and `--only-binary` entries in the output file generated by `uv pip compile`.
`emitFindLinks`	`boolean`	Include `--find-links` entries in the output file generated by `uv pip compile`.
`emitIndexAnnotation`	`boolean`	Include comment annotations indicating the index used to resolve each package (e.g., `# from https://pypi.org/simple`).
`emitIndexUrl`	`boolean`	Include `--index-url` and `--extra-index-url` entries in the output file generated by `uv pip compile`.
`emitMarkerExpression`	`boolean`	Whether to emit a marker string indicating the conditions under which the set of pinned dependencies is valid.
`excludeNewer`	`string`	Limit candidate packages to those that were uploaded prior to a given point in time.
`excludeNewerPackage`	`{[ key: string ]: string}`	Limit candidate packages for specific packages to those that were uploaded prior to the given date.
`extra`	`string[]`	Include optional dependencies from the specified extra; may be provided more than once.
`extraBuildDependencies`	`{[ key: string ]: any[]}`	Additional build dependencies for packages.
`extraBuildVariables`	`{[ key: string ]: {[ key: string ]: string}}`	Extra environment variables to set when building certain packages.
`extraIndexUrl`	`string[]`	Extra URLs of package indexes to use, in addition to `--index-url`.
`findLinks`	`string[]`	Locations to search for candidate distributions, in addition to those found in the registry indexes.
`forkStrategy`	`string`	The strategy to use when selecting multiple versions of a given package across Python versions and platforms.
`generateHashes`	`boolean`	Include distribution hashes in the output file.
`group`	`projen.python.uvConfig.PipGroupName[]`	Include the following dependency groups.
`indexStrategy`	`string`	The strategy to use when resolving against multiple index URLs.
`indexUrl`	`string`	The URL of the Python package index (by default: https://pypi.org/simple).
`keyringProvider`	`string`	Attempt to use `keyring` for authentication for index URLs.
`linkMode`	`string`	The method to use when installing packages from the global cache.
`noAnnotate`	`boolean`	Exclude comment annotations indicating the source of each package from the output file generated by `uv pip compile`.
`noBinary`	`string[]`	Don't install pre-built wheels.
`noBuild`	`boolean`	Don't build source distributions.
`noBuildIsolation`	`boolean`	Disable isolation when building source distributions.
`noBuildIsolationPackage`	`string[]`	Disable isolation when building source distributions for a specific package.
`noDeps`	`boolean`	Ignore package dependencies, instead only add those packages explicitly listed on the command line to the resulting requirements file.
`noEmitPackage`	`string[]`	Specify a package to omit from the output resolution.
`noExtra`	`string[]`	Exclude the specified optional dependencies if `all-extras` is supplied.
`noHeader`	`boolean`	Exclude the comment header at the top of output file generated by `uv pip compile`.
`noIndex`	`boolean`	Ignore all registry indexes (e.g., PyPI), instead relying on direct URL dependencies and those provided via `--find-links`.
`noSources`	`boolean`	Ignore the `tool.uv.sources` table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any local or Git sources.
`noStripExtras`	`boolean`	Include extras in the output file.
`noStripMarkers`	`boolean`	Include environment markers in the output file generated by `uv pip compile`.
`onlyBinary`	`string[]`	Only use pre-built wheels; don't build source distributions.
`outputFile`	`string`	Write the requirements generated by `uv pip compile` to the given `requirements.txt` file.
`prefix`	`string`	Install packages into `lib`, `bin`, and other top-level folders under the specified directory, as if a virtual environment were present at that location.
`prerelease`	`string`	The strategy to use when considering pre-release versions.
`python`	`string`	The Python interpreter into which packages should be installed.
`pythonPlatform`	`string`	The platform for which requirements should be resolved.
`pythonVersion`	`string`	The minimum Python version that should be supported by the resolved requirements (e.g., `3.8` or `3.8.17`).
`reinstall`	`boolean`	Reinstall all packages, regardless of whether they're already installed.
`reinstallPackage`	`string[]`	Reinstall a specific package, regardless of whether it's already installed.
`requireHashes`	`boolean`	Require a matching hash for each requirement.
`resolution`	`string`	The strategy to use when selecting between the different compatible versions for a given package requirement.
`strict`	`boolean`	Validate the Python environment, to detect packages with missing dependencies and other issues.
`system`	`boolean`	Install packages into the system Python environment.
`target`	`string`	Install packages into the specified directory, rather than into the virtual or system Python environment.
`torchBackend`	`string`	The backend to use when fetching packages in the PyTorch ecosystem.
`universal`	`boolean`	Perform a universal resolution, attempting to generate a single `requirements.txt` output file that is compatible with all operating systems, architectures, and Python implementations.
`upgrade`	`boolean`	Allow package upgrades, ignoring pinned versions in any existing output file.
`upgradePackage`	`string[]`	Allow upgrades for a specific package, ignoring pinned versions in any existing output file.
`verifyHashes`	`boolean`	Validate any hashes provided in the requirements file.

`allExtras`^Optional

public readonly allExtras: boolean;

Type: boolean

Include all optional dependencies.

Only applies to pyproject.toml, setup.py, and setup.cfg sources.

`allowEmptyRequirements`^Optional

public readonly allowEmptyRequirements: boolean;

Type: boolean

Allow uv pip sync with empty requirements, which will clear the environment of all packages.

`annotationStyle`^Optional

public readonly annotationStyle: string;

Type: string

The style of the annotation comments included in the output file, used to indicate the source of each package.

`breakSystemPackages`^Optional

public readonly breakSystemPackages: boolean;

Type: boolean

Allow uv to modify an EXTERNALLY-MANAGED Python installation.

WARNING: --break-system-packages is intended for use in continuous integration (CI) environments, when installing into Python installations that are managed by an external package manager, like apt. It should be used with caution, as such Python installations explicitly recommend against modifications by other package managers (like uv or pip).

`compileBytecode`^Optional

public readonly compileBytecode: boolean;

Type: boolean

Compile Python files to bytecode after installation.

By default, uv does not compile Python (.py) files to bytecode (__pycache__/*.pyc); instead, compilation is performed lazily the first time a module is imported. For use-cases in which start time is critical, such as CLI applications and Docker containers, this option can be enabled to trade longer installation times for faster start times.

When enabled, uv will process the entire site-packages directory (including packages that are not being modified by the current operation) for consistency. Like pip, it will also ignore errors.

`configSettings`^Optional

public readonly configSettings: {[ key: string ]: any};

Type: {[ key: string ]: any}

Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs.

`configSettingsPackage`^Optional

public readonly configSettingsPackage: {[ key: string ]: {[ key: string ]: any}};

Type: {[ key: string ]: {[ key: string ]: any}}

Settings to pass to the PEP 517 build backend for specific packages, specified as KEY=VALUE pairs.

`customCompileCommand`^Optional

public readonly customCompileCommand: string;

Type: string

The header comment to include at the top of the output file generated by uv pip compile.

Used to reflect custom build scripts and commands that wrap uv pip compile.

`dependencyMetadata`^Optional

public readonly dependencyMetadata: StaticMetadata[];

Type: projen.python.uvConfig.StaticMetadata[]

Pre-defined static metadata for dependencies of the project (direct or transitive).

When provided, enables the resolver to use the specified metadata instead of querying the registry or building the relevant package from source.

Metadata should be provided in adherence with the Metadata 2.3 standard, though only the following fields are respected:

name: The name of the package.
(Optional) version: The version of the package. If omitted, the metadata will be applied to all versions of the package.
(Optional) requires-dist: The dependencies of the package (e.g., werkzeug>=0.14).
(Optional) requires-python: The Python version required by the package (e.g., >=3.10).
(Optional) provides-extra: The extras provided by the package.

`emitBuildOptions`^Optional

public readonly emitBuildOptions: boolean;

Type: boolean

Include --no-binary and --only-binary entries in the output file generated by uv pip compile.

`emitFindLinks`^Optional

public readonly emitFindLinks: boolean;

Type: boolean

Include --find-links entries in the output file generated by uv pip compile.

`emitIndexAnnotation`^Optional

public readonly emitIndexAnnotation: boolean;

Type: boolean

Include comment annotations indicating the index used to resolve each package (e.g., # from https://pypi.org/simple).

`emitIndexUrl`^Optional

public readonly emitIndexUrl: boolean;

Type: boolean

Include --index-url and --extra-index-url entries in the output file generated by uv pip compile.

`emitMarkerExpression`^Optional

public readonly emitMarkerExpression: boolean;

Type: boolean

Whether to emit a marker string indicating the conditions under which the set of pinned dependencies is valid.

The pinned dependencies may be valid even when the marker expression is false, but when the expression is true, the requirements are known to be correct.

`excludeNewer`^Optional

public readonly excludeNewer: string;

Type: string

Limit candidate packages to those that were uploaded prior to a given point in time.

Accepts a superset of RFC 3339 (e.g., 2006-12-02T02:07:43Z). A full timestamp is required to ensure that the resolver will behave consistently across timezones.

`excludeNewerPackage`^Optional

public readonly excludeNewerPackage: {[ key: string ]: string};

Type: {[ key: string ]: string}

Limit candidate packages for specific packages to those that were uploaded prior to the given date.

Accepts package-date pairs in a dictionary format.

`extra`^Optional

public readonly extra: string[];

Type: string[]

Include optional dependencies from the specified extra; may be provided more than once.

Only applies to pyproject.toml, setup.py, and setup.cfg sources.

`extraBuildDependencies`^Optional

public readonly extraBuildDependencies: {[ key: string ]: any[]};

Type: {[ key: string ]: any[]}

Additional build dependencies for packages.

This allows extending the PEP 517 build environment for the project's dependencies with additional packages. This is useful for packages that assume the presence of packages like pip, and do not declare them as build dependencies.

`extraBuildVariables`^Optional

public readonly extraBuildVariables: {[ key: string ]: {[ key: string ]: string}};

Type: {[ key: string ]: {[ key: string ]: string}}

Extra environment variables to set when building certain packages.

Environment variables will be added to the environment when building the specified packages.

`extraIndexUrl`^Optional

public readonly extraIndexUrl: string[];

Type: string[]

Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by index_url. When multiple indexes are provided, earlier values take priority.

To control uv's resolution strategy when multiple indexes are present, see index_strategy.

`findLinks`^Optional

public readonly findLinks: string[];

Type: string[]

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

`forkStrategy`^Optional

public readonly forkStrategy: string;

Type: string

The strategy to use when selecting multiple versions of a given package across Python versions and platforms.

By default, uv will optimize for selecting the latest version of each package for each supported Python version (requires-python), while minimizing the number of selected versions across platforms.

Under fewest, uv will minimize the number of selected versions for each package, preferring older versions that are compatible with a wider range of supported Python versions or platforms.

`generateHashes`^Optional

public readonly generateHashes: boolean;

Type: boolean

Include distribution hashes in the output file.

`group`^Optional

public readonly group: PipGroupName[];

Type: projen.python.uvConfig.PipGroupName[]

Include the following dependency groups.

`indexStrategy`^Optional

public readonly indexStrategy: string;

Type: string

The strategy to use when resolving against multiple index URLs.

By default, uv will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

`indexUrl`^Optional

public readonly indexUrl: string;

Type: string

The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index provided by this setting is given lower priority than any indexes specified via extra_index_url.

`keyringProvider`^Optional

public readonly keyringProvider: string;

Type: string

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures uv to use the keyring CLI to handle authentication.

`linkMode`^Optional

public readonly linkMode: string;

Type: string
Default: clone(also known as Copy-on-Write) on macOS, andhardlink` on Linux and

The method to use when installing packages from the global cache.

Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and Windows.

WARNING: The use of symlink link mode is discouraged, as they create tight coupling between the cache and the target environment. For example, clearing the cache (uv cache clean) will break all installed packages by way of removing the underlying source files. Use symlinks with caution.

`noAnnotate`^Optional

public readonly noAnnotate: boolean;

Type: boolean

Exclude comment annotations indicating the source of each package from the output file generated by uv pip compile.

`noBinary`^Optional

public readonly noBinary: string[];

Type: string[]

Don't install pre-built wheels.

The given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available.

Multiple packages may be provided. Disable binaries for all packages with :all:. Clear previously specified packages with :none:.

`noBuild`^Optional

public readonly noBuild: boolean;

Type: boolean

Don't build source distributions.

When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

Alias for --only-binary :all:.

`noBuildIsolation`^Optional

public readonly noBuildIsolation: boolean;

Type: boolean

Disable isolation when building source distributions.

Assumes that build dependencies specified by PEP 518 are already installed.

`noBuildIsolationPackage`^Optional

public readonly noBuildIsolationPackage: string[];

Type: string[]

Disable isolation when building source distributions for a specific package.

Assumes that the packages' build dependencies specified by PEP 518 are already installed.

`noDeps`^Optional

public readonly noDeps: boolean;

Type: boolean

Ignore package dependencies, instead only add those packages explicitly listed on the command line to the resulting requirements file.

`noEmitPackage`^Optional

public readonly noEmitPackage: string[];

Type: string[]

Specify a package to omit from the output resolution.

Its dependencies will still be included in the resolution. Equivalent to pip-compile's --unsafe-package option.

`noExtra`^Optional

public readonly noExtra: string[];

Type: string[]

Exclude the specified optional dependencies if all-extras is supplied.

`noHeader`^Optional

public readonly noHeader: boolean;

Type: boolean

Exclude the comment header at the top of output file generated by uv pip compile.

`noIndex`^Optional

public readonly noIndex: boolean;

Type: boolean

Ignore all registry indexes (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links.

`noSources`^Optional

public readonly noSources: boolean;

Type: boolean

Ignore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any local or Git sources.

`noStripExtras`^Optional

public readonly noStripExtras: boolean;

Type: boolean

Include extras in the output file.

By default, uv strips extras, as any packages pulled in by the extras are already included as dependencies in the output file directly. Further, output files generated with --no-strip-extras cannot be used as constraints files in install and sync invocations.

`noStripMarkers`^Optional

public readonly noStripMarkers: boolean;

Type: boolean

Include environment markers in the output file generated by uv pip compile.

By default, uv strips environment markers, as the resolution generated by compile is only guaranteed to be correct for the target environment.

`onlyBinary`^Optional

public readonly onlyBinary: string[];

Type: string[]

Only use pre-built wheels; don't build source distributions.

When enabled, resolving will not run code from the given packages. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

Multiple packages may be provided. Disable binaries for all packages with :all:. Clear previously specified packages with :none:.

`outputFile`^Optional

public readonly outputFile: string;

Type: string

Write the requirements generated by uv pip compile to the given requirements.txt file.

If the file already exists, the existing versions will be preferred when resolving dependencies, unless --upgrade is also specified.

`prefix`^Optional

public readonly prefix: string;

Type: string

Install packages into lib, bin, and other top-level folders under the specified directory, as if a virtual environment were present at that location.

In general, prefer the use of --python to install into an alternate environment, as scripts and other artifacts installed via --prefix will reference the installing interpreter, rather than any interpreter added to the --prefix directory, rendering them non-portable.

`prerelease`^Optional

public readonly prerelease: string;

Type: string

The strategy to use when considering pre-release versions.

By default, uv will accept pre-releases for packages that only publish pre-releases, along with first-party requirements that contain an explicit pre-release marker in the declared specifiers (if-necessary-or-explicit).

`python`^Optional

public readonly python: string;

Type: string

The Python interpreter into which packages should be installed.

By default, uv installs into the virtual environment in the current working directory or any parent directory. The --python option allows you to specify a different interpreter, which is intended for use in continuous integration (CI) environments or other automated workflows.

Supported formats:

3.10 looks for an installed Python 3.10 in the registry on Windows (see py --list-paths), or python3.10 on Linux and macOS.
python3.10 or python.exe looks for a binary with the given name in PATH.
/home/ferris/.local/bin/python3.10 uses the exact Python at the given path.

`pythonPlatform`^Optional

public readonly pythonPlatform: string;

Type: string

The platform for which requirements should be resolved.

Represented as a "target triple", a string that describes the target platform in terms of its CPU, vendor, and operating system name, like x86_64-unknown-linux-gnu or aarch64-apple-darwin.

`pythonVersion`^Optional

public readonly pythonVersion: string;

Type: string

The minimum Python version that should be supported by the resolved requirements (e.g., 3.8 or 3.8.17).

If a patch version is omitted, the minimum patch version is assumed. For example, 3.8 is mapped to 3.8.0.

`reinstall`^Optional

public readonly reinstall: boolean;

Type: boolean

Reinstall all packages, regardless of whether they're already installed.

Implies refresh.

`reinstallPackage`^Optional

public readonly reinstallPackage: string[];

Type: string[]

Reinstall a specific package, regardless of whether it's already installed.

Implies refresh-package.

`requireHashes`^Optional

public readonly requireHashes: boolean;

Type: boolean

Require a matching hash for each requirement.

Hash-checking mode is all or nothing. If enabled, all requirements must be provided with a corresponding hash or set of hashes. Additionally, if enabled, all requirements must either be pinned to exact versions (e.g., ==1.0.0), or be specified via direct URL.

Hash-checking mode introduces a number of additional constraints:

Git dependencies are not supported.
Editable installations are not supported.
Local dependencies are not supported, unless they point to a specific wheel (.whl) or source archive (.zip, .tar.gz), as opposed to a directory.

`resolution`^Optional

public readonly resolution: string;

Type: string

The strategy to use when selecting between the different compatible versions for a given package requirement.

By default, uv will use the latest compatible version of each package (highest).

`strict`^Optional

public readonly strict: boolean;

Type: boolean

Validate the Python environment, to detect packages with missing dependencies and other issues.

`system`^Optional

public readonly system: boolean;

Type: boolean

Install packages into the system Python environment.

By default, uv installs into the virtual environment in the current working directory or any parent directory. The --system option instructs uv to instead use the first Python found in the system PATH.

WARNING: --system is intended for use in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.

`target`^Optional

public readonly target: string;

Type: string

Install packages into the specified directory, rather than into the virtual or system Python environment.

The packages will be installed at the top-level of the directory.

`torchBackend`^Optional

public readonly torchBackend: string;

Type: string

The backend to use when fetching packages in the PyTorch ecosystem.

When set, uv will ignore the configured index URLs for packages in the PyTorch ecosystem, and will instead use the defined backend.

For example, when set to cpu, uv will use the CPU-only PyTorch index; when set to cu126, uv will use the PyTorch index for CUDA 12.6.

The auto mode will attempt to detect the appropriate PyTorch index based on the currently installed CUDA drivers.

This option is in preview and may change in any future release.

`universal`^Optional

public readonly universal: boolean;

Type: boolean

Perform a universal resolution, attempting to generate a single requirements.txt output file that is compatible with all operating systems, architectures, and Python implementations.

In universal mode, the current Python version (or user-provided --python-version) will be treated as a lower bound. For example, --universal --python-version 3.7 would produce a universal resolution for Python 3.7 and later.

`upgrade`^Optional

public readonly upgrade: boolean;

Type: boolean

Allow package upgrades, ignoring pinned versions in any existing output file.

`upgradePackage`^Optional

public readonly upgradePackage: string[];

Type: string[]

Allow upgrades for a specific package, ignoring pinned versions in any existing output file.

Accepts both standalone package names (ruff) and version specifiers (ruff<0.5.0).

`verifyHashes`^Optional

public readonly verifyHashes: boolean;

Type: boolean

Validate any hashes provided in the requirements file.

Unlike --require-hashes, --verify-hashes does not require that all requirements have hashes; instead, it will limit itself to verifying the hashes of those requirements that do include them.

SchemaConflictItem

A single item in a conflicting set.

Each item is a pair of an (optional) package and a corresponding extra or group name for that package.

Initializer

import { python } from 'projen'

const schemaConflictItem: python.uvConfig.SchemaConflictItem = { ... }

Properties

Name	Type	Description
`extra`	`string`	No description.
`group`	`string`	No description.
`package`	`string`	No description.

`extra`^Optional

public readonly extra: string;

Type: string

`group`^Optional

public readonly group: string;

Type: string

`package`^Optional

public readonly package: string;

Type: string

StaticMetadata

A subset of the Python Package Metadata 2.3 standard as specified in https://packaging.python.org/specifications/core-metadata/.

Initializer

import { python } from 'projen'

const staticMetadata: python.uvConfig.StaticMetadata = { ... }

Properties

Name	Type	Description
`name`	`string`	No description.
`providesExtra`	`string[]`	No description.
`requiresDist`	`string[]`	No description.
`requiresPython`	`string`	PEP 508-style Python requirement, e.g., `>=3.10`.
`version`	`string`	PEP 440-style package version, e.g., `1.2.3`.

`name`^Required

public readonly name: string;

Type: string

`providesExtra`^Optional

public readonly providesExtra: string[];

Type: string[]

`requiresDist`^Optional

public readonly requiresDist: string[];

Type: string[]

`requiresPython`^Optional

public readonly requiresPython: string;

Type: string

PEP 508-style Python requirement, e.g., >=3.10.

`version`^Optional

public readonly version: string;

Type: string

PEP 440-style package version, e.g., 1.2.3.

ToolUvWorkspace

Initializer

import { python } from 'projen'

const toolUvWorkspace: python.uvConfig.ToolUvWorkspace = { ... }

Properties

Name	Type	Description
`exclude`	`string[]`	Packages to exclude as workspace members. If a package matches both `members` and `exclude`, it will be excluded.
`members`	`string[]`	Packages to include as workspace members.

`exclude`^Optional

public readonly exclude: string[];

Type: string[]

Packages to exclude as workspace members. If a package matches both members and exclude, it will be excluded.

Supports both globs and explicit paths.

For more information on the glob syntax, refer to the glob documentation.

`members`^Optional

public readonly members: string[];

Type: string[]

Packages to include as workspace members.

Supports both globs and explicit paths.

For more information on the glob syntax, refer to the glob documentation.

UvConfiguration

Metadata and configuration for uv.

Initializer

import { python } from 'projen'

const uvConfiguration: python.uvConfig.UvConfiguration = { ... }

Properties

Name	Type	Description
`addBounds`	`string`	The default version specifier when adding a dependency.
`allowInsecureHost`	`string[]`	Allow insecure connections to host.
`buildBackend`	`projen.python.uvConfig.BuildBackendSettings`	Configuration for the uv build backend.
`buildConstraintDependencies`	`string[]`	PEP 508-style requirements, e.g., `ruff==0.5.0`, or `ruff @ https://...`.
`cacheDir`	`string`	Path to the cache directory.
`cacheKeys`	`any[]`	The keys to consider when caching builds for the project.
`checkUrl`	`string`	Check an index URL for existing files to skip duplicate uploads.
`compileBytecode`	`boolean`	Compile Python files to bytecode after installation.
`concurrentBuilds`	`number`	The maximum number of source distributions that uv will build concurrently at any given time.
`concurrentDownloads`	`number`	The maximum number of in-flight concurrent downloads that uv will perform at any given time.
`concurrentInstalls`	`number`	The number of threads used when installing and unzipping packages.
`configSettings`	`{[ key: string ]: any}`	Settings to pass to the PEP 517 build backend, specified as `KEY=VALUE` pairs.
`configSettingsPackage`	`{[ key: string ]: {[ key: string ]: any}}`	Settings to pass to the PEP 517 build backend for specific packages, specified as `KEY=VALUE` pairs.
`conflicts`	`projen.python.uvConfig.SchemaConflictItem[][]`	A list of sets of conflicting groups or extras.
`constraintDependencies`	`string[]`	PEP 508-style requirements, e.g., `ruff==0.5.0`, or `ruff @ https://...`.
`defaultGroups`	`any`	The list of `dependency-groups` to install by default.
`dependencyGroups`	`{[ key: string ]: projen.python.uvConfig.DependencyGroupSettings}`	Additional settings for `dependency-groups`.
`dependencyMetadata`	`projen.python.uvConfig.StaticMetadata[]`	Pre-defined static metadata for dependencies of the project (direct or transitive).
`devDependencies`	`string[]`	PEP 508-style requirements, e.g., `ruff==0.5.0`, or `ruff @ https://...`.
`environments`	`string[]`	A list of environment markers, e.g., `python_version >= '3.6'`.
`excludeDependencies`	`string[]`	Package names to exclude, e.g., `werkzeug`, `numpy`.
`excludeNewer`	`string`	Limit candidate packages to those that were uploaded prior to a given point in time.
`excludeNewerPackage`	`{[ key: string ]: string}`	Limit candidate packages for specific packages to those that were uploaded prior to the given date.
`extraBuildDependencies`	`{[ key: string ]: any[]}`	Additional build dependencies for packages.
`extraBuildVariables`	`{[ key: string ]: {[ key: string ]: string}}`	Extra environment variables to set when building certain packages.
`extraIndexUrl`	`string[]`	Extra URLs of package indexes to use, in addition to `--index-url`.
`findLinks`	`string[]`	Locations to search for candidate distributions, in addition to those found in the registry indexes.
`forkStrategy`	`string`	The strategy to use when selecting multiple versions of a given package across Python versions and platforms.
`index`	`projen.python.uvConfig.Index[]`	The indexes to use when resolving dependencies.
`indexStrategy`	`string`	The strategy to use when resolving against multiple index URLs.
`indexUrl`	`string`	The URL of the Python package index (by default: https://pypi.org/simple).
`keyringProvider`	`string`	Attempt to use `keyring` for authentication for index URLs.
`linkMode`	`string`	The method to use when installing packages from the global cache.
`managed`	`boolean`	Whether the project is managed by uv.
`nativeTls`	`boolean`	Whether to load TLS certificates from the platform's native certificate store.
`noBinary`	`boolean`	Don't install pre-built wheels.
`noBinaryPackage`	`string[]`	Don't install pre-built wheels for a specific package.
`noBuild`	`boolean`	Don't build source distributions.
`noBuildIsolation`	`boolean`	Disable isolation when building source distributions.
`noBuildIsolationPackage`	`string[]`	Disable isolation when building source distributions for a specific package.
`noBuildPackage`	`string[]`	Don't build source distributions for a specific package.
`noCache`	`boolean`	Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation.
`noIndex`	`boolean`	Ignore all registry indexes (e.g., PyPI), instead relying on direct URL dependencies and those provided via `--find-links`.
`noSources`	`boolean`	Ignore the `tool.uv.sources` table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any local or Git sources.
`offline`	`boolean`	Disable network access, relying only on locally cached data and locally available files.
`overrideDependencies`	`string[]`	PEP 508-style requirements, e.g., `ruff==0.5.0`, or `ruff @ https://...`.
`package`	`boolean`	Whether the project should be considered a Python package, or a non-package ("virtual") project.
`pip`	`projen.python.uvConfig.PipOptions`	No description.
`prerelease`	`string`	The strategy to use when considering pre-release versions.
`preview`	`boolean`	Whether to enable experimental, preview features.
`publishUrl`	`string`	The URL for publishing packages to the Python package index (by default: https://upload.pypi.org/legacy/).
`pypyInstallMirror`	`string`	Mirror URL to use for downloading managed PyPy installations.
`pythonDownloads`	`string`	Whether to allow Python downloads.
`pythonDownloadsJsonUrl`	`string`	URL pointing to JSON of custom Python installations.
`pythonInstallMirror`	`string`	Mirror URL for downloading managed Python installations.
`pythonPreference`	`string`	Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv.
`reinstall`	`boolean`	Reinstall all packages, regardless of whether they're already installed.
`reinstallPackage`	`string[]`	Reinstall a specific package, regardless of whether it's already installed.
`requiredEnvironments`	`string[]`	A list of environment markers, e.g., `sys_platform == 'darwin'.
`requiredVersion`	`string`	Enforce a requirement on the version of uv.
`resolution`	`string`	The strategy to use when selecting between the different compatible versions for a given package requirement.
`sources`	`{[ key: string ]: any[]}`	The sources to use when resolving dependencies.
`trustedPublishing`	`projen.python.uvConfig.TrustedPublishing`	Configure trusted publishing.
`upgrade`	`boolean`	Allow package upgrades, ignoring pinned versions in any existing output file.
`upgradePackage`	`string[]`	Allow upgrades for a specific package, ignoring pinned versions in any existing output file.
`workspace`	`projen.python.uvConfig.ToolUvWorkspace`	The workspace definition for the project, if any.

`addBounds`^Optional

public readonly addBounds: string;

Type: string

The default version specifier when adding a dependency.

When adding a dependency to the project, if no constraint or URL is provided, a constraint is added based on the latest compatible version of the package. By default, a lower bound constraint is used, e.g., >=1.2.3.

When --frozen is provided, no resolution is performed, and dependencies are always added without constraints.

This option is in preview and may change in any future release.

`allowInsecureHost`^Optional

public readonly allowInsecureHost: string[];

Type: string[]

Allow insecure connections to host.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

`buildBackend`^Optional

public readonly buildBackend: BuildBackendSettings;

Type: projen.python.uvConfig.BuildBackendSettings

Configuration for the uv build backend.

Note that those settings only apply when using the uv_build backend, other build backends (such as hatchling) have their own configuration.

`buildConstraintDependencies`^Optional

public readonly buildConstraintDependencies: string[];

Type: string[]

PEP 508-style requirements, e.g., ruff==0.5.0, or ruff @ https://....

`cacheDir`^Optional

public readonly cacheDir: string;

Type: string

Path to the cache directory.

`cacheKeys`^Optional

public readonly cacheKeys: any[];

Type: any[]

The keys to consider when caching builds for the project.

Cache keys enable you to specify the files or directories that should trigger a rebuild when modified. By default, uv will rebuild a project whenever the pyproject.toml, setup.py, or setup.cfg files in the project directory are modified, or if a src directory is added or removed, i.e.:

cache-keys = [{ file = "pyproject.toml" }, { file = "setup.py" }, { file = "setup.cfg" }, { dir = "src" }]

As an example: if a project uses dynamic metadata to read its dependencies from a requirements.txt file, you can specify cache-keys = [{ file = "requirements.txt" }, { file = "pyproject.toml" }] to ensure that the project is rebuilt whenever the requirements.txt file is modified (in addition to watching the pyproject.toml).

Globs are supported, following the syntax of the glob crate. For example, to invalidate the cache whenever a .toml file in the project directory or any of its subdirectories is modified, you can specify cache-keys = [{ file = "*_/*.toml" }]. Note that the use of globs can be expensive, as uv may need to walk the filesystem to determine whether any files have changed.

Cache keys can also include version control information. For example, if a project uses setuptools_scm to read its version from a Git commit, you can specify cache-keys = [{ git = { commit = true }, { file = "pyproject.toml" }] to include the current Git commit hash in the cache key (in addition to the pyproject.toml). Git tags are also supported via cache-keys = [{ git = { commit = true, tags = true } }].

Cache keys can also include environment variables. For example, if a project relies on MACOSX_DEPLOYMENT_TARGET or other environment variables to determine its behavior, you can specify cache-keys = [{ env = "MACOSX_DEPLOYMENT_TARGET" }] to invalidate the cache whenever the environment variable changes.

Cache keys only affect the project defined by the pyproject.toml in which they're specified (as opposed to, e.g., affecting all members in a workspace), and all paths and globs are interpreted as relative to the project directory.

`checkUrl`^Optional

public readonly checkUrl: string;

Type: string

Check an index URL for existing files to skip duplicate uploads.

This option allows retrying publishing that failed after only some, but not all files have been uploaded, and handles error due to parallel uploads of the same file.

Before uploading, the index is checked. If the exact same file already exists in the index, the file will not be uploaded. If an error occurred during the upload, the index is checked again, to handle cases where the identical file was uploaded twice in parallel.

The exact behavior will vary based on the index. When uploading to PyPI, uploading the same file succeeds even without --check-url, while most other indexes error.

The index must provide one of the supported hashes (SHA-256, SHA-384, or SHA-512).

`compileBytecode`^Optional

public readonly compileBytecode: boolean;

Type: boolean

Compile Python files to bytecode after installation.

When enabled, uv will process the entire site-packages directory (including packages that are not being modified by the current operation) for consistency. Like pip, it will also ignore errors.

`concurrentBuilds`^Optional

public readonly concurrentBuilds: number;

Type: number
Default: the number of available CPU cores.

The maximum number of source distributions that uv will build concurrently at any given time.

Defaults to the number of available CPU cores.

`concurrentDownloads`^Optional

public readonly concurrentDownloads: number;

Type: number

The maximum number of in-flight concurrent downloads that uv will perform at any given time.

`concurrentInstalls`^Optional

public readonly concurrentInstalls: number;

Type: number
Default: the number of available CPU cores.

The number of threads used when installing and unzipping packages.

Defaults to the number of available CPU cores.

`configSettings`^Optional

public readonly configSettings: {[ key: string ]: any};

Type: {[ key: string ]: any}

Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs.

`configSettingsPackage`^Optional

public readonly configSettingsPackage: {[ key: string ]: {[ key: string ]: any}};

Type: {[ key: string ]: {[ key: string ]: any}}

Settings to pass to the PEP 517 build backend for specific packages, specified as KEY=VALUE pairs.

Accepts a map from package names to string key-value pairs.

`conflicts`^Optional

public readonly conflicts: SchemaConflictItem[][];

Type: projen.python.uvConfig.SchemaConflictItem[][]

A list of sets of conflicting groups or extras.

`constraintDependencies`^Optional

public readonly constraintDependencies: string[];

Type: string[]

PEP 508-style requirements, e.g., ruff==0.5.0, or ruff @ https://....

`defaultGroups`^Optional

public readonly defaultGroups: any;

Type: any

The list of dependency-groups to install by default.

Can also be the literal "all" to default enable all groups.

`dependencyGroups`^Optional

public readonly dependencyGroups: {[ key: string ]: DependencyGroupSettings};

Type: {[ key: string ]: projen.python.uvConfig.DependencyGroupSettings}

Additional settings for dependency-groups.

Currently this can only be used to add requires-python constraints to dependency groups (typically to inform uv that your dev tooling has a higher python requirement than your actual project).

This cannot be used to define dependency groups, use the top-level [dependency-groups] table for that.

`dependencyMetadata`^Optional

public readonly dependencyMetadata: StaticMetadata[];

Type: projen.python.uvConfig.StaticMetadata[]

Pre-defined static metadata for dependencies of the project (direct or transitive).

When provided, enables the resolver to use the specified metadata instead of querying the registry or building the relevant package from source.

Metadata should be provided in adherence with the Metadata 2.3 standard, though only the following fields are respected:

name: The name of the package.
(Optional) version: The version of the package. If omitted, the metadata will be applied to all versions of the package.
(Optional) requires-dist: The dependencies of the package (e.g., werkzeug>=0.14).
(Optional) requires-python: The Python version required by the package (e.g., >=3.10).
(Optional) provides-extra: The extras provided by the package.

`devDependencies`^Optional

public readonly devDependencies: string[];

Type: string[]

PEP 508-style requirements, e.g., ruff==0.5.0, or ruff @ https://....

`environments`^Optional

public readonly environments: string[];

Type: string[]

A list of environment markers, e.g., python_version >= '3.6'.

`excludeDependencies`^Optional

public readonly excludeDependencies: string[];

Type: string[]

Package names to exclude, e.g., werkzeug, numpy.

`excludeNewer`^Optional

public readonly excludeNewer: string;

Type: string

Limit candidate packages to those that were uploaded prior to a given point in time.

Accepts a superset of RFC 3339 (e.g., 2006-12-02T02:07:43Z). A full timestamp is required to ensure that the resolver will behave consistently across timezones.

`excludeNewerPackage`^Optional

public readonly excludeNewerPackage: {[ key: string ]: string};

Type: {[ key: string ]: string}

Limit candidate packages for specific packages to those that were uploaded prior to the given date.

Accepts package-date pairs in a dictionary format.

`extraBuildDependencies`^Optional

public readonly extraBuildDependencies: {[ key: string ]: any[]};

Type: {[ key: string ]: any[]}

Additional build dependencies for packages.

`extraBuildVariables`^Optional

public readonly extraBuildVariables: {[ key: string ]: {[ key: string ]: string}};

Type: {[ key: string ]: {[ key: string ]: string}}

Extra environment variables to set when building certain packages.

Environment variables will be added to the environment when building the specified packages.

`extraIndexUrl`^Optional

public readonly extraIndexUrl: string[];

Type: string[]

Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by index_url or index with default = true. When multiple indexes are provided, earlier values take priority.

To control uv's resolution strategy when multiple indexes are present, see index_strategy.

(Deprecated: use index instead.)

`findLinks`^Optional

public readonly findLinks: string[];

Type: string[]

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

`forkStrategy`^Optional

public readonly forkStrategy: string;

Type: string

The strategy to use when selecting multiple versions of a given package across Python versions and platforms.

By default, uv will optimize for selecting the latest version of each package for each supported Python version (requires-python), while minimizing the number of selected versions across platforms.

Under fewest, uv will minimize the number of selected versions for each package, preferring older versions that are compatible with a wider range of supported Python versions or platforms.

`index`^Optional

public readonly index: Index[];

Type: projen.python.uvConfig.Index[]

The indexes to use when resolving dependencies.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

Indexes are considered in the order in which they're defined, such that the first-defined index has the highest priority. Further, the indexes provided by this setting are given higher priority than any indexes specified via index_url or extra_index_url. uv will only consider the first index that contains a given package, unless an alternative index strategy is specified.

If an index is marked as explicit = true, it will be used exclusively for the dependencies that select it explicitly via [tool.uv.sources], as in:

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu121"
explicit = true

[tool.uv.sources]
torch = { index = "pytorch" }

If an index is marked as default = true, it will be moved to the end of the prioritized list, such that it is given the lowest priority when resolving packages. Additionally, marking an index as default will disable the PyPI default index.

`indexStrategy`^Optional

public readonly indexStrategy: string;

Type: string

The strategy to use when resolving against multiple index URLs.

`indexUrl`^Optional

public readonly indexUrl: string;

Type: string

The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index provided by this setting is given lower priority than any indexes specified via extra_index_url or index.

(Deprecated: use index instead.)

`keyringProvider`^Optional

public readonly keyringProvider: string;

Type: string

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures uv to use the keyring CLI to handle authentication.

`linkMode`^Optional

public readonly linkMode: string;

Type: string
Default: clone(also known as Copy-on-Write) on macOS, andhardlink` on Linux and

The method to use when installing packages from the global cache.

Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and Windows.

`managed`^Optional

public readonly managed: boolean;

Type: boolean

Whether the project is managed by uv.

If false, uv will ignore the project when uv run is invoked.

`nativeTls`^Optional

public readonly nativeTls: boolean;

Type: boolean

Whether to load TLS certificates from the platform's native certificate store.

By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

`noBinary`^Optional

public readonly noBinary: boolean;

Type: boolean

Don't install pre-built wheels.

The given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available.

`noBinaryPackage`^Optional

public readonly noBinaryPackage: string[];

Type: string[]

Don't install pre-built wheels for a specific package.

`noBuild`^Optional

public readonly noBuild: boolean;

Type: boolean

Don't build source distributions.

`noBuildIsolation`^Optional

public readonly noBuildIsolation: boolean;

Type: boolean

Disable isolation when building source distributions.

Assumes that build dependencies specified by PEP 518 are already installed.

`noBuildIsolationPackage`^Optional

public readonly noBuildIsolationPackage: string[];

Type: string[]

Disable isolation when building source distributions for a specific package.

Assumes that the packages' build dependencies specified by PEP 518 are already installed.

`noBuildPackage`^Optional

public readonly noBuildPackage: string[];

Type: string[]

Don't build source distributions for a specific package.

`noCache`^Optional

public readonly noCache: boolean;

Type: boolean

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation.

`noIndex`^Optional

public readonly noIndex: boolean;

Type: boolean

Ignore all registry indexes (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links.

`noSources`^Optional

public readonly noSources: boolean;

Type: boolean

Ignore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any local or Git sources.

`offline`^Optional

public readonly offline: boolean;

Type: boolean

Disable network access, relying only on locally cached data and locally available files.

`overrideDependencies`^Optional

public readonly overrideDependencies: string[];

Type: string[]

PEP 508-style requirements, e.g., ruff==0.5.0, or ruff @ https://....

`package`^Optional

public readonly package: boolean;

Type: boolean

Whether the project should be considered a Python package, or a non-package ("virtual") project.

Packages are built and installed into the virtual environment in editable mode and thus require a build backend, while virtual projects are not built or installed; instead, only their dependencies are included in the virtual environment.

Creating a package requires that a build-system is present in the pyproject.toml, and that the project adheres to a structure that adheres to the build backend's expectations (e.g., a src layout).

`pip`^Optional

public readonly pip: PipOptions;

Type: projen.python.uvConfig.PipOptions

`prerelease`^Optional

public readonly prerelease: string;

Type: string

The strategy to use when considering pre-release versions.

`preview`^Optional

public readonly preview: boolean;

Type: boolean

Whether to enable experimental, preview features.

`publishUrl`^Optional

public readonly publishUrl: string;

Type: string

The URL for publishing packages to the Python package index (by default: https://upload.pypi.org/legacy/).

`pypyInstallMirror`^Optional

public readonly pypyInstallMirror: string;

Type: string

Mirror URL to use for downloading managed PyPy installations.

By default, managed PyPy installations are downloaded from downloads.python.org. This variable can be set to a mirror URL to use a different source for PyPy installations. The provided URL will replace https://downloads.python.org/pypy in, e.g., https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2.

Distributions can be read from a local directory by using the file:// URL scheme.

`pythonDownloads`^Optional

public readonly pythonDownloads: string;

Type: string

Whether to allow Python downloads.

`pythonDownloadsJsonUrl`^Optional

public readonly pythonDownloadsJsonUrl: string;

Type: string

URL pointing to JSON of custom Python installations.

Note that currently, only local paths are supported.

`pythonInstallMirror`^Optional

public readonly pythonInstallMirror: string;

Type: string

Mirror URL for downloading managed Python installations.

By default, managed Python installations are downloaded from python-build-standalone. This variable can be set to a mirror URL to use a different source for Python installations. The provided URL will replace https://github.com/astral-sh/python-build-standalone/releases/download in, e.g., https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz.

Distributions can be read from a local directory by using the file:// URL scheme.

`pythonPreference`^Optional

public readonly pythonPreference: string;

Type: string

Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv.

`reinstall`^Optional

public readonly reinstall: boolean;

Type: boolean

Reinstall all packages, regardless of whether they're already installed.

Implies refresh.

`reinstallPackage`^Optional

public readonly reinstallPackage: string[];

Type: string[]

Reinstall a specific package, regardless of whether it's already installed.

Implies refresh-package.

`requiredEnvironments`^Optional

public readonly requiredEnvironments: string[];

Type: string[]

A list of environment markers, e.g., `sys_platform == 'darwin'.

`requiredVersion`^Optional

public readonly requiredVersion: string;

Type: string

Enforce a requirement on the version of uv.

If the version of uv does not meet the requirement at runtime, uv will exit with an error.

Accepts a PEP 440 specifier, like ==0.5.0 or >=0.5.0.

`resolution`^Optional

public readonly resolution: string;

Type: string

The strategy to use when selecting between the different compatible versions for a given package requirement.

By default, uv will use the latest compatible version of each package (highest).

`sources`^Optional

public readonly sources: {[ key: string ]: any[]};

Type: {[ key: string ]: any[]}

The sources to use when resolving dependencies.

tool.uv.sources enriches the dependency metadata with additional sources, incorporated during development. A dependency source can be a Git repository, a URL, a local path, or an alternative registry.

See Dependencies for more.

`trustedPublishing`^Optional

public readonly trustedPublishing: TrustedPublishing;

Type: projen.python.uvConfig.TrustedPublishing

Configure trusted publishing.

By default, uv checks for trusted publishing when running in a supported environment, but ignores it if it isn't configured.

uv's supported environments for trusted publishing include GitHub Actions and GitLab CI/CD.

`upgrade`^Optional

public readonly upgrade: boolean;

Type: boolean

Allow package upgrades, ignoring pinned versions in any existing output file.

`upgradePackage`^Optional

public readonly upgradePackage: string[];

Type: string[]

Allow upgrades for a specific package, ignoring pinned versions in any existing output file.

Accepts both standalone package names (ruff) and version specifiers (ruff<0.5.0).

`workspace`^Optional

public readonly workspace: ToolUvWorkspace;

Type: projen.python.uvConfig.ToolUvWorkspace

The workspace definition for the project, if any.

WheelDataIncludes

Data includes for wheels.

See BuildBackendSettings::data.

Initializer

import { python } from 'projen'

const wheelDataIncludes: python.uvConfig.WheelDataIncludes = { ... }

Properties

Name	Type	Description
`data`	`string`	No description.
`headers`	`string`	No description.
`platlib`	`string`	No description.
`purelib`	`string`	No description.
`scripts`	`string`	No description.

`data`^Optional

public readonly data: string;

Type: string

`headers`^Optional

public readonly headers: string;

Type: string

`platlib`^Optional

public readonly platlib: string;

Type: string

`purelib`^Optional

public readonly purelib: string;

Type: string

`scripts`^Optional

public readonly scripts: string;

Type: string

Enums

TrustedPublishing

Members

Name	Description
`ALWAYS`	always.
`NEVER`	never.

`ALWAYS`

always.

`NEVER`

never.

Structs ​

BuildBackendSettings ​

Initializer ​

Properties ​

dataOptional ​

defaultExcludesOptional ​

moduleNameOptional ​

moduleRootOptional ​

namespaceOptional ​

sourceExcludeOptional ​

sourceIncludeOptional ​

wheelExcludeOptional ​

DependencyGroupSettings ​

Initializer ​

Properties ​

requiresPythonOptional ​

Index ​

Initializer ​

Properties ​

urlRequired ​

authenticateOptional ​

cacheControlOptional ​

defaultOptional ​

explicitOptional ​

formatOptional ​

ignoreErrorCodesOptional ​

nameOptional ​

publishUrlOptional ​

IndexCacheControl ​

Initializer ​

Properties ​

apiOptional ​

filesOptional ​

PipGroupName ​

Initializer ​

Properties ​

nameRequired ​

pathOptional ​

PipOptions ​

Initializer ​

Properties ​

allExtrasOptional ​

allowEmptyRequirementsOptional ​

annotationStyleOptional ​

breakSystemPackagesOptional ​

compileBytecodeOptional ​

configSettingsOptional ​

configSettingsPackageOptional ​

customCompileCommandOptional ​

dependencyMetadataOptional ​

emitBuildOptionsOptional ​

emitFindLinksOptional ​

emitIndexAnnotationOptional ​

emitIndexUrlOptional ​

emitMarkerExpressionOptional ​

excludeNewerOptional ​

excludeNewerPackageOptional ​

extraOptional ​

extraBuildDependenciesOptional ​

extraBuildVariablesOptional ​

extraIndexUrlOptional ​

findLinksOptional ​

forkStrategyOptional ​

generateHashesOptional ​

groupOptional ​

indexStrategyOptional ​

indexUrlOptional ​

keyringProviderOptional ​

linkModeOptional ​

noAnnotateOptional ​

noBinaryOptional ​

noBuildOptional ​

noBuildIsolationOptional ​

noBuildIsolationPackageOptional ​

noDepsOptional ​

noEmitPackageOptional ​

noExtraOptional ​

noHeaderOptional ​

noIndexOptional ​

noSourcesOptional ​

Structs

BuildBackendSettings

Initializer

Properties

`data`^Optional

`defaultExcludes`^Optional

`moduleName`^Optional

`moduleRoot`^Optional

`namespace`^Optional

`sourceExclude`^Optional

`sourceInclude`^Optional

`wheelExclude`^Optional

DependencyGroupSettings

Initializer

Properties

`requiresPython`^Optional

Index

Initializer

Properties

`url`^Required

`authenticate`^Optional

`cacheControl`^Optional

`default`^Optional

`explicit`^Optional

`format`^Optional

`ignoreErrorCodes`^Optional

`name`^Optional

`publishUrl`^Optional

IndexCacheControl

Initializer

Properties

`api`^Optional

`files`^Optional

PipGroupName

Initializer

Properties

`name`^Required

`path`^Optional

PipOptions

Initializer

Properties

`allExtras`^Optional

`allowEmptyRequirements`^Optional

`annotationStyle`^Optional

`breakSystemPackages`^Optional

`compileBytecode`^Optional

`configSettings`^Optional

`configSettingsPackage`^Optional

`customCompileCommand`^Optional

`dependencyMetadata`^Optional

`emitBuildOptions`^Optional

`emitFindLinks`^Optional

`emitIndexAnnotation`^Optional

`emitIndexUrl`^Optional

`emitMarkerExpression`^Optional

`excludeNewer`^Optional

`excludeNewerPackage`^Optional

`extra`^Optional

`extraBuildDependencies`^Optional

`extraBuildVariables`^Optional

`extraIndexUrl`^Optional

`findLinks`^Optional

`forkStrategy`^Optional

`generateHashes`^Optional

`group`^Optional

`indexStrategy`^Optional

`indexUrl`^Optional

`keyringProvider`^Optional

`linkMode`^Optional

`noAnnotate`^Optional

`noBinary`^Optional

`noBuild`^Optional

`noBuildIsolation`^Optional

`noBuildIsolationPackage`^Optional

`noDeps`^Optional

`noEmitPackage`^Optional

`noExtra`^Optional

`noHeader`^Optional

`noIndex`^Optional

`noSources`^Optional