
--8<-- [start:description]

`pixi publish` **builds** a conda package from your workspace and **uploads** it to a channel.

- With a target URL: builds and uploads to the specified destination.
- Without a target URL: builds and copies the package to the current working directory.

The target URL determines the upload backend:

| URL pattern | Backend |
|-------------|---------|
| `https://prefix.dev/<channel>` | [prefix.dev](https://prefix.dev) |
| `https://anaconda.org/<owner>` | [Anaconda.org](https://anaconda.org) |
| `s3://bucket-name/channel` | S3-compatible storage |
| `channel:///path/to/channel` | Local filesystem channel |
| `file:///path/to/dir` | Copy to local directory |
| `quetz://server/<channel>` | [Quetz](https://github.com/mamba-org/quetz) |
| `artifactory://server/<channel>` | [JFrog Artifactory](https://jfrog.com/artifactory/) |

--8<-- [end:description]

--8<-- [start:example]

## Examples

### Build and copy to current directory

Omit the target URL to build and copy the resulting package to the current working directory.

```shell
# Build the package and copy it to the current directory
pixi publish
```

### Publishing to prefix.dev

The most common use case is publishing packages to a channel on [prefix.dev](https://prefix.dev).

```shell
# Build and publish to your prefix.dev channel
pixi publish https://prefix.dev/my-channel

# Build for a specific target platform and publish
pixi publish https://prefix.dev/my-channel --target-platform linux-64

# Publish with sigstore attestation for supply chain security
pixi publish https://prefix.dev/my-channel --generate-attestation

# Force overwrite existing packages
pixi publish https://prefix.dev/my-channel --force
```

For authentication, either log in first with `pixi auth login`, or set the `PREFIX_API_KEY` environment variable:

```shell
# Option 1: Log in (credentials are stored in the keychain)
pixi auth login --token $MY_TOKEN https://prefix.dev
pixi publish https://prefix.dev/my-channel

# Option 2: Use trusted publishing in CI (no credentials needed)
pixi publish https://prefix.dev/my-channel
```

See the [prefix.dev deployment guide](../../../deployment/prefix.md) for more details on setting up channels and trusted publishing.

### Publishing to Anaconda.org

```shell
# Build and publish to your Anaconda.org account
pixi publish https://anaconda.org/my-username

# Publish to a specific label/channel
pixi publish https://anaconda.org/my-username/dev
```

### Publishing to S3

When publishing to S3, the channel is automatically initialized (if new) and indexed after the upload.

```shell
# Build and publish to an S3 bucket (using AWS credentials from environment)
pixi publish s3://my-bucket/my-channel
```

S3 credentials are resolved from the standard AWS credential chain (environment variables, shared credentials file, instance profiles, etc.).

### Publishing to a local filesystem channel

Local channels are useful for development and testing. The channel directory is automatically created and indexed.

```shell
# Build and publish to a local channel
pixi publish channel:///path/to/my-channel

# Force overwrite if the package already exists
pixi publish channel:///path/to/my-channel --force
```

### Copying to a local path

Use `file://` or a bare path to copy the built `.conda` artifact directly to a directory, without creating a channel structure.

```shell
# Copy the built package to a directory (file:// URL)
pixi publish file:///path/to/output/dir

# Bare paths also work -- relative or absolute
pixi publish /tmp/my-packages
pixi publish ../my-packages
```

If the directory looks like a conda channel (contains `repodata.json`), pixi warns that you may have meant to use `channel://` instead.

### Publishing from a specific manifest

```shell
# Publish a package from a specific recipe
pixi publish https://prefix.dev/my-channel --path ./my-recipe/recipe.yaml

# Publish from a different workspace
pixi publish https://prefix.dev/my-channel --path ./my-project/
```

### Clean rebuild and publish

```shell
# Clean the build directory before building and publishing
pixi publish https://prefix.dev/my-channel --clean
```

## Authentication

`pixi publish` uses the same authentication system as other pixi commands. Credentials can be configured in three ways:

1. **Keychain / auth-file**: Use `pixi auth login` to store credentials
   ```shell
   pixi auth login --token $MY_TOKEN https://prefix.dev
   ```

2. **Trusted publishing (CI)**: On GitHub Actions, GitLab CI, or Google Cloud, prefix.dev supports OIDC-based trusted publishing — no stored secrets required. See the [prefix.dev trusted publishing guide](../../../deployment/prefix.md#trusted-publishing).

3. **Environment variables**:
   - `PREFIX_API_KEY` for prefix.dev
   - `ANACONDA_API_KEY` for Anaconda.org
   - `QUETZ_API_KEY` for Quetz
   - `ARTIFACTORY_TOKEN` for Artifactory
   - Standard AWS environment variables for S3

--8<-- [end:example]
