0
# Build System
1

2
UV provides comprehensive package building and publishing capabilities, supporting modern Python packaging standards (PEP 517/518) with fast builds, multiple output formats, and seamless integration with PyPI and private indexes.
3

4
## Capabilities
5

6
### Package Building
7

8
Build Python packages into distributable formats with automatic dependency resolution and platform-specific optimizations.
9

10
```bash { .api }
11
uv build [PATH]
12
# Builds Python packages from source
13
# Default PATH is current directory
14

15
# Build targets:
16
# - Source distribution (sdist)
17
# - Binary distribution (wheel)
18
# - Both (default behavior)
19

20
# Options:
21
# --sdist                  # Build source distribution only
22
# --wheel                  # Build wheel only
23
# --out-dir DIR           # Output directory (default: dist/)
24
# --config-setting KEY=VALUE  # Pass settings to build backend
25
# --no-build-isolation    # Disable build isolation
26
# --skip-dependency-check # Skip build dependency verification
27
# --python VERSION        # Target Python version
28
```
29

30
Usage examples:
31

32
```bash
33
# Build both sdist and wheel (default)
34
uv build
35

36
# Build only source distribution
37
uv build --sdist
38

39
# Build only wheel
40
uv build --wheel
41

42
# Build to custom directory
43
uv build --out-dir packages/
44

45
# Build specific project directory
46
uv build ./my-package/
47

48
# Pass settings to build backend
49
uv build --config-setting="--global-option=--with-cython"
50
```
51

52
### Package Publishing
53

54
Upload built distributions to PyPI, TestPyPI, or private package indexes with authentication and verification.
55

56
```bash { .api }
57
uv publish [DIST...]
58
# Publishes distributions to package index
59
# Default: publishes all files in dist/ directory
60

61
# Target formats:
62
# - Source distributions (.tar.gz)
63
# - Wheel distributions (.whl)
64
# - Both
65

66
# Options:
67
# --repository URL         # Repository URL (default: PyPI)
68
# --repository-url URL     # Alternate repository URL
69
# --username USERNAME      # Authentication username
70
# --password PASSWORD      # Authentication password
71
# --token TOKEN           # API token for authentication
72
# --config-file FILE      # Configuration file path
73
# --skip-existing         # Skip files that already exist
74
# --verify-ssl           # Verify SSL certificates (default: true)
75
# --no-verify-ssl        # Disable SSL verification
76
# --cert FILE            # Client certificate file
77
# --client-cert FILE     # Client certificate file
78
# --verbose              # Verbose output
79
```
80

81
Usage examples:
82

83
```bash
84
# Publish all distributions in dist/
85
uv publish
86

87
# Publish specific files
88
uv publish dist/mypackage-1.0.0.tar.gz dist/mypackage-1.0.0-py3-none-any.whl
89

90
# Publish to TestPyPI
91
uv publish --repository testpypi
92

93
# Publish with API token
94
uv publish --token $PYPI_TOKEN
95

96
# Publish with username/password
97
uv publish --username myuser --password mypass
98

99
# Publish to private index
100
uv publish --repository-url https://private.pypi.org/simple/
101

102
# Skip existing files
103
uv publish --skip-existing
104
```
105

106
### Build Configuration
107

108
Configure build behavior through project settings and build system integration.
109

110
Build system configuration in `pyproject.toml`:
111
```toml { .api }
112
[build-system]
113
requires = ["hatchling"]              # Build dependencies
114
build-backend = "hatchling.build"    # Build backend
115

116
[project]
117
name = "my-package"
118
version = "1.0.0"
119
description = "Package description"
120
authors = [
121
    {name = "Author Name", email = "author@example.com"}
122
]
123
dependencies = [
124
    "requests>=2.25.0",
125
]
126
requires-python = ">=3.8"
127

128
[project.optional-dependencies]
129
dev = ["pytest", "black", "ruff"]
130
docs = ["mkdocs", "mkdocs-material"]
131

132
[project.scripts]
133
my-tool = "my_package.cli:main"
134

135
[project.gui-scripts]
136
my-gui = "my_package.gui:main"
137

138
[project.entry-points."my_package.plugins"]
139
plugin1 = "my_package.plugins:plugin1"
140
```
141

142
UV-specific build configuration:
143
```toml { .api }
144
[tool.uv]
145
# Build settings
146
build-backend = "hatchling"          # Preferred build backend
147
build-isolation = true               # Enable build isolation
148
build-verbosity = 1                  # Build verbosity level
149

150
# Source distribution settings
151
include-patterns = [
152
    "src/**/*.py",
153
    "tests/**/*.py",
154
    "README.md",
155
    "LICENSE",
156
]
157
exclude-patterns = [
158
    "**/__pycache__",
159
    "**/*.pyc",
160
    ".git/**",
161
]
162
```
163

164
### Build Backend Integration
165

166
UV integrates with popular Python build backends and tools:
167

168
#### Hatchling
169
```toml { .api }
170
[build-system]
171
requires = ["hatchling"]
172
build-backend = "hatchling.build"
173

174
[tool.hatch.build.targets.sdist]
175
include = [
176
    "/src",
177
    "/tests",
178
    "/README.md",
179
]
180

181
[tool.hatch.build.targets.wheel]
182
packages = ["src/my_package"]
183
```
184

185
#### Setuptools
186
```toml { .api }
187
[build-system]
188
requires = ["setuptools>=61.0", "wheel"]
189
build-backend = "setuptools.build_meta"
190

191
[tool.setuptools]
192
packages = ["my_package"]
193
package-dir = {"" = "src"}
194
```
195

196
#### PDM-Backend
197
```toml { .api }
198
[build-system]
199
requires = ["pdm-backend"]
200
build-backend = "pdm.backend"
201

202
[tool.pdm.build]
203
includes = ["src"]
204
excludes = ["tests"]
205
```
206

207
#### Flit
208
```toml { .api }
209
[build-system]
210
requires = ["flit_core >=3.2,<4"]
211
build-backend = "flit_core.buildapi"
212

213
[project]
214
name = "my-package"
215
authors = [{name = "Author", email = "author@example.com"}]
216
dynamic = ["version", "description"]
217
```
218

219
### Build Isolation
220

221
UV uses build isolation by default to ensure reproducible builds:
222

223
1. **Isolated environment**: Creates temporary virtual environment
224
2. **Build dependencies**: Installs only declared build requirements
225
3. **Clean builds**: No interference from existing packages
226
4. **Reproducibility**: Consistent results across different machines
227

228
Disable isolation for debugging:
229
```bash
230
uv build --no-build-isolation
231
```
232

233
### Multi-platform Building
234

235
Build packages for multiple platforms and Python versions:
236

237
```bash { .api }
238
# Build with specific Python version
239
uv build --python 3.12
240

241
# Build configuration for multiple platforms
242
[tool.cibuildwheel]
243
build = "cp38-* cp39-* cp310-* cp311-* cp312-*"
244
skip = "*-win32 *-manylinux_i686"
245

246
# Build with cibuildwheel integration
247
uv tool run cibuildwheel --platform linux
248
```
249

250
### Package Metadata
251

252
Configure package metadata for proper distribution:
253

254
```toml { .api }
255
[project]
256
name = "my-package"
257
version = "1.0.0"
258
description = "Short package description"
259
readme = "README.md"
260
license = {text = "MIT"}
261
authors = [
262
    {name = "Author Name", email = "author@example.com"}
263
]
264
maintainers = [
265
    {name = "Maintainer", email = "maintainer@example.com"}
266
]
267
keywords = ["keyword1", "keyword2"]
268
classifiers = [
269
    "Development Status :: 4 - Beta",
270
    "Intended Audience :: Developers",
271
    "License :: OSI Approved :: MIT License",
272
    "Programming Language :: Python :: 3",
273
    "Programming Language :: Python :: 3.8",
274
    "Programming Language :: Python :: 3.9",
275
    "Programming Language :: Python :: 3.10",
276
    "Programming Language :: Python :: 3.11",
277
    "Programming Language :: Python :: 3.12",
278
]
279

280
[project.urls]
281
Homepage = "https://github.com/user/repo"
282
Documentation = "https://docs.example.com"
283
Repository = "https://github.com/user/repo"
284
"Bug Tracker" = "https://github.com/user/repo/issues"
285
```
286

287
### Publishing Configuration
288

289
Configure publishing targets and authentication:
290

291
```toml { .api }
292
# .pypirc configuration file
293
[distutils]
294
index-servers =
295
    pypi
296
    testpypi
297
    private
298

299
[pypi]
300
repository = https://upload.pypi.org/legacy/
301
username = __token__
302
password = pypi-token-here
303

304
[testpypi]
305
repository = https://test.pypi.org/legacy/
306
username = __token__
307
password = testpypi-token-here
308

309
[private]
310
repository = https://private.pypi.org/simple/
311
username = user
312
password = pass
313
```
314

315
Environment variables for authentication:
316
```bash { .api }
317
TWINE_USERNAME=__token__
318
TWINE_PASSWORD=pypi-token
319
TWINE_REPOSITORY_URL=https://upload.pypi.org/legacy/
320
```
321

322
### Build Artifacts
323

324
UV build produces standard Python distribution artifacts:
325

326
#### Source Distribution (.tar.gz)
327
Contains:
328
- Source code files
329
- Package metadata (PKG-INFO)
330
- Build scripts and configuration
331
- Documentation and data files
332

333
#### Wheel Distribution (.whl)
334
Contains:
335
- Compiled Python code (.pyc files)
336
- Package metadata (METADATA, WHEEL)
337
- Entry points and console scripts
338
- Data files and resources
339

340
### Build Verification
341

342
Verify built packages before publishing:
343

344
```bash { .api }
345
# Check package metadata
346
uv tool run twine check dist/*
347

348
# Test installation from built wheel
349
uv pip install dist/package-1.0.0-py3-none-any.whl
350

351
# Test package functionality
352
uv run python -c "import package; package.test()"
353
```
354

355
### Continuous Integration
356

357
Integrate building and publishing into CI/CD pipelines:
358

359
```yaml { .api }
360
# GitHub Actions example
361
name: Build and Publish
362
on: [push, pull_request]
363

364
jobs:
365
  build:
366
    runs-on: ubuntu-latest
367
    steps:
368
    - uses: actions/checkout@v4
369
    - name: Set up Python
370
      uses: actions/setup-python@v4
371
      with:
372
        python-version: '3.12'
373
    - name: Install UV
374
      run: pip install uv
375
    - name: Build package
376
      run: uv build
377
    - name: Check built package
378
      run: uv tool run twine check dist/*
379
    - name: Publish to PyPI
380
      if: startsWith(github.ref, 'refs/tags/')
381
      env:
382
        TWINE_USERNAME: __token__
383
        TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
384
      run: uv publish
385
```
386

387
### Build Troubleshooting
388

389
Common build issues and solutions:
390

391
#### Missing build dependencies
392
```bash
393
# Install build dependencies manually
394
uv pip install build setuptools wheel
395

396
# Or use build isolation (default)
397
uv build
398
```
399

400
#### Build backend errors
401
```bash
402
# Check build backend configuration
403
cat pyproject.toml | grep -A 5 "\[build-system\]"
404

405
# Try different backend
406
[build-system]
407
requires = ["setuptools>=61.0"]
408
build-backend = "setuptools.build_meta"
409
```
410

411
#### Permission issues
412
```bash
413
# Check output directory permissions
414
ls -la dist/
415

416
# Use custom output directory
417
uv build --out-dir ./packages/
418
```
419

420
#### Publishing failures
421
```bash
422
# Verify credentials
423
uv publish --repository testpypi
424

425
# Check package name availability
426
uv tool run twine check dist/*
427

428
# Skip existing files
429
uv publish --skip-existing
430
```