Install & Compatibility
Where this runs
tested against v7.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.335s · 38.7MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.2s · import 0.319s · 39MB
37MB installed
● package 37MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Updater
✓ from tuf.ngclient import Updater
Metadata
✓ from tuf.api.metadata import Metadata
Used for low-level metadata object manipulation.
Root
✓ from tuf.api.metadata import Root
Represents the Root metadata role object.
TargetFile
✓ from tuf.api.metadata import TargetFile
Represents information about a target file.
This quickstart demonstrates how to initialize a TUF client (`tuf.ngclient.Updater`) to securely fetch and verify a target file from a TUF repository. It assumes a `root.json` file is available out-of-band for initial trust bootstrapping and that a repository is serving metadata and targets. For a runnable example, you would need to set up a dummy TUF repository (e.g., using `tuf.repository` utilities, though it's not stable API, or a dedicated repository service like RSTUF) and provide a valid initial `root.json`.
import os
import shutil
from pathlib import Path
from tuf.ngclient import Updater
# --- Configuration (replace with your actual repository details) ---
REPO_METADATA_URL = os.environ.get('TUF_METADATA_URL', 'http://localhost:8000/metadata/')
REPO_TARGETS_URL = os.environ.get('TUF_TARGETS_URL', 'http://localhost:8000/targets/')
# Ensure a clean client state for demonstration
LOCAL_CACHE_DIR = Path('./client_cache')
LOCAL_DOWNLOAD_DIR = Path('./client_downloads')
ROOT_METADATA_PATH = Path('./initial_root.json')
if LOCAL_CACHE_DIR.exists():
shutil.rmtree(LOCAL_CACHE_DIR)
if LOCAL_DOWNLOAD_DIR.exists():
shutil.rmtree(LOCAL_DOWNLOAD_DIR)
LOCAL_CACHE_DIR.mkdir(parents=True, exist_ok=True)
LOCAL_DOWNLOAD_DIR.mkdir(parents=True, exist_ok=True)
# --- Simulate pre-packaged initial root metadata ---
# In a real application, this 'root.json' would be securely bundled
# with your application and stored in a read-only location.
# For this example, let's create a dummy one if it doesn't exist.
# You would typically copy a valid initial_root.json here.
if not ROOT_METADATA_PATH.exists():
print("WARNING: Creating a dummy initial_root.json. "
"In production, this file must be a trusted, pre-packaged root metadata.")
with open(ROOT_METADATA_PATH, 'w') as f:
f.write('{}') # Placeholder, will cause errors if not a real root.
print(f"Initializing TUF Updater with metadata_url='{REPO_METADATA_URL}' and targets_url='{REPO_TARGETS_URL}'")
print(f"Local cache: {LOCAL_CACHE_DIR}, Downloads: {LOCAL_DOWNLOAD_DIR}")
try:
# Initialize TUF Updater
updater = Updater(
repository_dir=str(LOCAL_CACHE_DIR), # Local directory for storing metadata
metadata_base_url=REPO_METADATA_URL,
target_base_url=REPO_TARGETS_URL,
initial_root_metadata=ROOT_METADATA_PATH.read_bytes() # Bootstrap trust from bundled root
)
# Refresh top-level metadata (root, timestamp, snapshot, targets)
print("Refreshing top-level metadata...")
updater.refresh()
print("Metadata refreshed successfully.")
# Get information about a target file
TARGET_NAME = "example_target.txt" # Replace with an actual target name on your repo
print(f"Getting target info for '{TARGET_NAME}'...")
target_info = updater.get_targetinfo(TARGET_NAME)
if target_info:
print(f"Found target '{TARGET_NAME}' (size: {target_info.length} bytes, hashes: {target_info.hashes}).")
# Download the target file
target_path = LOCAL_DOWNLOAD_DIR / TARGET_NAME
print(f"Downloading target to '{target_path}'...")
updater.download_target(target_info, str(target_path))
print(f"Target '{TARGET_NAME}' downloaded and verified successfully!")
else:
print(f"Target '{TARGET_NAME}' not found or could not be verified.")
except Exception as e:
print(f"An error occurred: {e}")
print("Please ensure a TUF repository is running at the configured URLs "
"and that 'initial_root.json' is a valid, trusted root metadata file.")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'requests'
Upgrading to `tuf` v6.0.0 without accounting for the switch from `requests` to `urllib3` as the default HTTP client for `ngclient`.
fixIf your application explicitly relies on the `RequestsFetcher` (which is now deprecated), install `requests` explicitly: `pip install requests`. Otherwise, `tuf.ngclient` will use `urllib3` by default.
RepositoryError: Local root.json is invalid.
The initial root metadata file provided to the `Updater` is malformed, corrupted, or not a valid TUF root metadata file.
fixEnsure the `initial_root_metadata` argument to `Updater` (or the file path provided) points to a correctly formatted and trusted `root.json` file. Validate the JSON structure and its contents against the TUF specification.
Permission denied: '.../.sigstore/root.json'
The TUF client attempts to write or update metadata in a directory where the running user lacks write permissions, or the cached root metadata is in a read-only location.
fixEnsure the `repository_dir` provided to `Updater` is writable by the user running the client. For the initial trusted `root.json`, store it in a securely managed, typically read-only, path and pass its content via `initial_root_metadata`.
ValueError: unrecognized metadata type "<UNKNOWN_TYPE>"
Attempting to load or parse a TUF metadata file (`root.json`, `targets.json`, etc.) with an invalid `_type` field within its signed payload, or a corrupted file.
fixVerify the integrity and correctness of the metadata file. Ensure it conforms to the TUF specification for the respective role (e.g., `_type` should be 'root', 'targets', 'snapshot', or 'timestamp').
Upgrade
Version history
7.0.0latest on PyPI · released May 18, 2026
Audit
Dependencies
securesystemslibrequiredProvides core cryptographic routines; minimum v1.0.0 is required since tuf v5.0.0 for repository operations and full cryptographic capabilities.
urllib3requiredDefault HTTP library used by ngclient since v6.0.0.
requestsoptionalRequired only if explicitly using the deprecated RequestsFetcher for the ngclient.