Packages·3 min read
Rust packages (crates)
Publish a Rust crate to Zaryn with cargo, use it from another project, keep it private, and fix the usual errors. Every step explained.
Rust's package manager, **cargo**, can download crates from more than one registry. You tell it about Zaryn once, and from then on `cargo publish`, `cargo add` and `cargo build` work with Zaryn the same way they work with crates.io.
> Only want crates.io to download faster? You don't need any of this page: see [the crates.io mirror](/docs/en/package-mirrors#rust-crates). Can't install Rust itself because static.rust-lang.org is out of reach? See [rustup through Zaryn](/docs/en/package-mirrors#rust-itself-rustup).
## Tell cargo about Zaryn (once per computer)
Open (or create) the file `~/.cargo/config.toml`, the settings file cargo reads every time it runs, and add:
```toml
[registries.zaryn]
index = "sparse+https://api.zaryn.xyz/v1/packages/cargo/index/"
```
- `[registries.zaryn]` gives the registry a short name, `zaryn`, that you'll use in commands.
- `index` is where cargo looks up which crates and versions exist. `sparse+` means it asks for one small file per crate instead of downloading a list of everything.
## Get a token and log in
On [Packages](/packages), press **Create a publish token** and copy it. Then:
```bash
cargo login --registry zaryn
```
Paste the token when cargo asks. cargo keeps it in `~/.cargo/credentials.toml`, so you only do this once.
## Publish
In your crate's `Cargo.toml`, make sure the `[package]` part has a `description` and a `license`, and say where it may be published:
```toml
[package]
name = "hello-zaryn"
version = "0.1.0"
edition = "2021"
description = "Says hello"
license = "MIT"
publish = ["zaryn"] # only ever to Zaryn, never by accident to crates.io
```
Then:
```bash
cargo publish --registry zaryn
```
cargo builds the crate once to make sure it compiles, packs it into a `.crate` file and uploads it. The crate appears on [Packages](/packages) right away.
To publish a fix, raise `version` (for example to `0.1.1`) and run `cargo publish --registry zaryn` again. A version that's already published can't be replaced.
## Use it from another project
```bash
cargo add --registry zaryn hello-zaryn
```
That adds this line to `Cargo.toml` (you can also write it by hand):
```toml
[dependencies]
hello-zaryn = { version = "0.1", registry = "zaryn" }
```
`cargo build` downloads it from Zaryn. Your crate can depend on crates.io crates as usual; cargo fetches each from where it lives.
## Private crates (Premium)
A crate becomes private on its page: open it from [Packages](/packages) and press **Make private**. Only you, or the members of the organization that owns it, can see and install it.
Reading a private crate needs your token on every request, so it goes through a second registry name:
```toml
[registries.zaryn-private]
index = "sparse+https://api.zaryn.xyz/v1/packages/cargo/private/index/"
credential-provider = "cargo:token"
```
```bash
cargo login --registry zaryn-private
cargo add --registry zaryn-private my-secret-crate
```
The private index also lists your public crates, so a team can use just `zaryn-private`.
## Everyday commands
| To… | Run |
|---|---|
| find crates on Zaryn | `cargo search --registry zaryn hello` |
| hide a broken version | `cargo yank --registry zaryn --version 0.1.0 hello-zaryn` |
| bring it back | `cargo yank --registry zaryn --version 0.1.0 --undo hello-zaryn` |
Yanking doesn't delete anything: projects whose `Cargo.lock` already uses that version keep building. New projects just won't choose it.
## When something goes wrong
| cargo says | What it means | Fix |
|---|---|---|
| `401` or "this index needs a token" | cargo has no token for this registry | `cargo login --registry zaryn` (or `zaryn-private`) |
| "this token can't publish packages" | the token lacks `package:write` | create a new one on [Packages](/packages) |
| "this package name belongs to someone else" | another account published that name first | choose another name |
| "crate `foo_bar` already exists…" | `foo-bar` and `foo_bar` count as the same name, as on crates.io | choose another name |
| "this version is already published" | versions can't be replaced | raise `version` in `Cargo.toml` |
| "package storage on the Free plan is full" | your packages and images use 500 MB | yanked versions still count; [Premium](/billing) has 100 GB |
| `no matching package named …` | wrong registry name, or a private crate through `zaryn` | check the `registry =` in `Cargo.toml` |
## How it works
Zaryn speaks cargo's own registry protocol: the sparse index (one file per crate listing every version, its dependencies and features), the download address, and the publish, yank and search API. Each `.crate` file is stored by its SHA-256 hash, and that hash is in the index, so cargo checks every download and refuses a file that doesn't match.