Skip to content
ProfitOps · PFN Studio PFN Studio

Search is only available in production builds. Try building and previewing the site to test it out locally.

Publish to HuggingFace

A completed run lives on PFN Studio’s storage by default. Publishing pushes the checkpoint, topology, and a model card to a HuggingFace repo so any PFN Studio user (or huggingface_hub user) can pull it.

What gets pushed

Every published run produces a HF repo with this layout:

<your-hf-username>/<slug>/
├── checkpoint/
│   ├── model.pt          # PyTorch state_dict (the trained weights)
│   └── topology.json     # architecture spec — what `model.pt` was trained for
├── README.md             # auto-generated model card
└── pfnstudio.yaml        # the run's effective config (prior + model + hyperparams)

The topology.json is the contract — any client (PFN Studio, a Python script, the Predict API) reads it to know how to load model.pt. Don’t edit it by hand.

Before you start

  • A completed training run with status completed (follow Train your first model if you don’t have one)
  • A HuggingFace account
  • A HuggingFace write token with write scope. Generate one at https://huggingface.co/settings/tokens
  • The token added to PFN Studio: avatar menu → Settings → API tokens → Add HuggingFace token

1. Open the run

Navigate to the run you want to publish: /projects/<id>/runs/<runId>. The run must show Status: completed in its right-hand panel.

2. Click Publish

Top-right of the run page, next to Re-run. The publish dialog opens with:

  • Repo name — defaults to <your-username>/<project-slug>-<run-slug>. Change if you want a different name
  • Visibility — private (default) or public. Private repos require your HF token to pull; public ones don’t
  • Model card draft — auto-populated from the run’s config + eval results. Edit before publishing or leave as-is

Click Publish. PFN Studio pushes the checkpoint + topology + card and shows the resulting HF URL in the success toast.

3. Use it from another PFN Studio project

In a new project’s run config, set the checkpoint_ref to your HF repo:

checkpoint_ref:
  model.pt: hf://<your-hf-username>/<repo>/checkpoint/model.pt
  topology.json: hf://<your-hf-username>/<repo>/checkpoint/topology.json

PFN Studio’s hf:// resolver pulls the files at run time. For private repos, the resolver uses the HF token saved in Settings.

4. Use it from Python

from huggingface_hub import hf_hub_download
import torch, json


ckpt = hf_hub_download("<your-hf-username>/<repo>", "checkpoint/model.pt")
topo = json.load(open(hf_hub_download("<your-hf-username>/<repo>", "checkpoint/topology.json")))


# Reconstruct the architecture from topology.json, then load state_dict
model = build_model_from_topology(topo)
model.load_state_dict(torch.load(ckpt))

For the full example, see Predict API → Call from Python.

5. Make it discoverable in the Marketplace

To surface your published model in PFN Studio’s Marketplace:

  1. Open Marketplace → Publish a listing
  2. Pick Model as the listing type
  3. Paste your HF repo URL into studyGithubUrl (despite the name, it accepts HF too)
  4. Fill in the persona, citations, and JTBD fields
  5. Publish

Other PFN Studio users can now find your model on the Marketplace tab, install it, and clone it into their own projects.

Updating a published model

Push a new run to the same repo by re-publishing from the new run with the same Repo name. PFN Studio creates a new HF commit; the previous version stays in the repo’s history (HF retains all commits).

If you want each retrain to land on a new repo (clean lineage), append a date or version to the name: <repo>-v2, <repo>-2026-06.

Common errors

ErrorCauseFix
401 UnauthorizedHF token missing or expiredAdd a fresh write token in Settings → API tokens
403 Forbidden — repo lockedPushing to a repo you don’t ownPick a name under your own username
Repo exists with different topologyYou’re overwriting a repo whose topology.json doesn’t match this runUse a new repo name (rare, only if you retrained with a different architecture)
Worker timed out uploading checkpointSlow network on the workerRe-run publish; it’s idempotent

Next steps