---
url: /en/artifact/cargo.md
description: >
  Guide for configuring credentials and using the CNB Cargo artifact registry to
  push and pull Rust packages, covering both local CLI and CI pipeline
  workflows.
---
## Configure Credentials

Update the `.cargo/config.toml` file under the current project, add the following lines:

```toml
[registry]
default = "cnb-cargo-repo"
global-credential-providers = ["cargo:token"]

[registries.cnb-cargo-repo]
index = "sparse+<CNB_CARGO_URL>"
```

Use the following command to configure credentials:

```shell
echo ${CNB_TOKEN} | cargo login --registry cnb-cargo-repo
```

To get `<CNB_CARGO_URL>`, see [Obtaining the Artifact Registry Address](./intro.md#obtaining-the-artifact-registry-address).

To get `<CNB_TOKEN>`, see [Creating an Access Token](./intro.md#creating-an-access-token).

## Push Artifacts

### Local Command Line Push

1. Follow the above [Configure Credentials](#configure-credentials)

2. Execute the following command to publish to CNB:

```shell
cargo publish
```

### Push in Cloud Native Build

After completing the `.cargo/config.toml` configuration in the repository (see [Configure Credentials](#configure-credentials) above), commit to the repository and push a Tag to trigger the build:

```yaml title=".cnb.yml"
$:
  tag_push:
    - docker:
        image: docker.cnb.cool/examples/language/rust-1.87
      stages:
        - name: update version
          script: sed -i "s#^version = .*#version = \"${CNB_BRANCH}\"#" Cargo.toml
        - name: cargo login
          script: echo ${CNB_TOKEN} | cargo login --registry cnb-cargo-repo
        - name: cargo publish
          script: cargo publish --allow-dirty
```

The `update version` step in the pipeline automatically writes the Tag value into the `version` field of `Cargo.toml`.

### Push in Workspaces

1. Paste the following content into `.cnb.yml`, after committing to the repository, click the **「Workspace」** button in the upper right corner of the repository page to enter the development environment:

```yaml title=".cnb.yml"
$:
  vscode:
    - docker:
        image: docker.cnb.cool/examples/language/rust-1.87
      services:
        - vscode
        - docker
```

2. After entering, follow the [Configure Credentials](#configure-credentials) steps above, update the version in `Cargo.toml`, then publish:

```shell
cargo publish
```

## Use Artifacts

### Pull Artifacts

After following the above [Configure Credentials](#configure-credentials), use the following command to pull artifacts:

```shell
cargo add rand
```

### Yank/Unyank Artifacts

```shell
cargo yank my-crate@0.1.0
cargo yank my-crate@0.1.0 --undo
```

### Delete Artifacts

Cargo does not provide a delete command. Please refer to [Deleting Artifacts](./intro.md#deleting-artifacts).

## FAQ

### Q1: How to configure global credentials

Global configuration paths are as follows:

Windows: `%USERPROFILE%\.cargo\config.toml`

Unix: `$HOME/.cargo/config.toml`

For more usage, refer to the [official documentation](https://doc.rust-lang.org/cargo/reference/config.html).

### Q2: Cargo version requirements

Cargo 1.73.0 or later is recommended.

Versions below 1.73.0 have insufficient support for private repositories — in some scenarios, credentials may not be passed correctly, leading to authentication failures.

### Q3: When uploading an open-source package to CNB, it prompts that the artifact version already exists

CNB proxies the official source by default. When a package does not exist on the server, it is automatically served from the proxy, causing the Cargo client to mistakenly believe the package already exists on CNB.

To resolve this, upload a non-existent version as a placeholder first, then upload the correct version.