# Model weights Push, pull, list, share and delete your org's model weights from Python, and all but sharing from the privatemind command. > [!NOTE] > Needs the SDK at version 0.9.0 or later: `pip install -U "privatemind>=0.9"`. Workspaces come with an older version, so upgrade there too. The registry is switched on per organisation; see [Registry](https://docs.privatemind.com/registry.html) for what it holds, who can see what, and the quota. Your org's model weights live in the [registry](https://docs.privatemind.com/registry.html) as versions. From Python, `Client().weights` pushes a folder as a version, pulls one back, and manages models. From a shell, the `privatemind` command pushes, pulls, lists and deletes. In a workspace or a job the key is already configured. Elsewhere, set `PRIVATEMIND_TOKEN` to a personal [API key](https://docs.privatemind.com/api-keys.html). A workspace launched before the registry was released has a key without registry access, and calls raise `ForbiddenError` with `Missing required scope: weights:read`. Restarting it keeps that key, so launch a new workspace. ## Push ```python from privatemind import Client client = Client() pushed = client.weights.push("./out", "credit-ft", "2026-11-16") print(pushed.digest, pushed.size_bytes) print(sum(f.uploaded for f in pushed.files), "of", len(pushed.files), "files sent") ``` Every file under the folder becomes part of the version, except dotfiles, dot folders, `.git` and `__pycache__`. Links inside the folder are followed. From 0.10.0, a link that points outside the folder stops the push with `ValidationError`, unless you pass `follow_external_links=True`. A file name with a colon, a backslash or a control character, or anything that is not a regular file or folder, stops the push with `ValidationError`. Within a model each file is stored once. A file the model already holds at the same path, from an earlier version or a push that stopped halfway, is not sent again. To finish a push that broke off, run the same push again within two days. | Argument | Default | Notes | |---|---|---| | `folder` | required | The folder to push. | | `name` | required | The model: lowercase letters and digits joined by `.`, `_`, `-` or `/`. | | `version` | required | Letters, digits, `.`, `_` and `-`, up to 128 characters, not starting with `.` or `-`. | | `exclude` | none | Glob patterns to leave out, matched against each path inside the folder and against the file or folder name. A folder that matches is left out whole. | | `allow_pickle` | `False` | Push `.bin`, `.pt`, `.pth`, `.pkl` and `.ckpt` files. Loading one can run code hidden in it, so without this the push stops and names them. | | `follow_external_links` | `False` | Push files that links point to outside the folder, for example a Hugging Face cache snapshot whose files link into its blobs folder. Without this the push stops and names the link. | | `progress` | none | Called with each `WeightsFile` once it is sent or found already there. | It returns a `WeightsPush` with `name`, `version`, `digest`, `size_bytes`, `image` (the pinned name, `models//@sha256:…`) and `files`, each a `WeightsFile` with `path`, `size_bytes`, `digest` and `uploaded`. Versions are immutable: pushing one that already exists raises `ConflictError` before anything is sent. The registry's own refusals, such as a full quota, raise an error that carries the registry's message. ## Pull ```python pulled = client.weights.pull("credit-ft:2026-11-16", "./credit-ft") print(pulled.path, len(pulled.files)) ``` The reference is `:` or `@sha256:`. The pull checks each file against its digest as it arrives, and moves a file into place only once it matches. It writes only regular files and folders inside `dest`, and refuses a link, an absolute path or a `..`. `progress` is called with each file's path and size once it is in place. It returns a `WeightsPull` with `ref`, `digest`, `path`, `size_bytes` and `files`. ## List, inspect, share and delete | Call | What it does | |---|---| | `client.weights.list()` | The models you can read, as a `WeightsList` with `models`, your org's registry `path`, `used_bytes` and `quota_bytes`. | | `client.weights.get(name)` | One model as a `WeightsModel`: `owner`, `visibility`, `description`, `size_bytes`, `last_pushed_at`, and its `versions`, newest first. Each `WeightsVersion` carries `version`, `digest`, `size_bytes`, `pushed_at`, and `used_by`, the workspaces, jobs and model servers that use it. Workloads of other members that are private to them are counted in `used_by_hidden` and not named. | | `client.weights.share(name)` | Shares the model with everyone in the org who has compute access. `share(name, shared=False)` makes it private again, which is refused with `ConflictError` while another member's workload uses it. | | `client.weights.delete(name, version)` | Deletes one version. Leave out `version` to delete the model and every version. A version in use by any workload, running or stopped, raises `ConflictError` naming what uses it. | `share` and `delete` need your own API key, as the model's owner or an org admin. A workspace or job key can list, push and pull, and gets `ForbiddenError` for these two. ## Use a version in a job or a model server ```python import privatemind as pm job = pm.submit_job( "python train.py --base /home/privatemind/models/credit-ft", template="pytorch-gpu", gpus=1, weights=["credit-ft:2026-11-16"], ) server = pm.launch_model_server( "gpu-cluster", gpus=1, weights="credit-ft:2026-11-16", vllm_version="v0.32.0", ) ``` A job takes a list of up to 8 versions and mounts each read-only under `/home/privatemind/models/`. Pass `{"name": "base", "ref": "credit-ft:2026-11-16"}` to choose the folder. A model server takes one version as its model. Both pin the version to its digest: a job when you submit it, a server when you launch it. See [Workspace jobs](https://docs.privatemind.com/sdk-jobs.html) and [Model servers](https://docs.privatemind.com/sdk-model-servers.html). ## The command line The SDK installs a `privatemind` command for push, pull, list and delete. Sharing is done from Python or the app. | Command | What it does | |---|---| | `privatemind weights push :` | Push a folder. Takes `--exclude PATTERN`, repeatable, `--allow-pickle` and `--follow-external-links`. | | `privatemind weights pull : ` | Download a version into a folder. | | `privatemind weights list` | Your models, with versions, size, sharing, owner and last push, and your org's usage. | | `privatemind weights list ` | One model's versions, with what uses each. | | `privatemind weights delete :` | Delete one version. `privatemind weights delete ` deletes the model and every version. | The command reads `PRIVATEMIND_TOKEN`, and `PRIVATEMIND_APP_URL` when you point it somewhere other than the production platform. It exits non-zero on any error and prints the reason. ## HTTP API The SDK calls the [Registry API](https://docs.privatemind.com/registry-api.html), which you can call directly from any language.