---
title: "Install and upgrade packages"
url: "https://docs.alisx.com/how-to/alis-build/install-and-upgrade-packages/"
---
# Install and upgrade packages

Pull a service's generated packages and bump its Alis dependencies with the CLI, which refreshes the private registry credentials and runs the right package manager for you.

## Prerequisites

- A service folder with at least one manifest: `go.mod`, `package.json`, a Python manifest, `pubspec.yaml`, a .NET project, a Swift package or a `Cargo.toml`.
- The service's contract has been defined at least once. An install that fails with "no published definition yet" means you must run `alis define <pkg>` first.

The package id always selects the service whose manifests change; it is never the dependency to add. Inside the service folder it can be omitted.

## Install after cloning or defining

```bash title="Terminal"
alis packages install acme.sh.orders.v1
```

This installs everything the manifests declare (`go mod tidy`, `pnpm install`, `pip` or `uv`, `dart pub get`) and then pulls the latest version of the service's own contract package. A fresh clone needs this once before any build, run or test.

- `--language go|node|python|dart|dotnet|swift|rust` limits the run to one language.
- `--version <definition-version>` installs that exact contract version instead of the latest.
- `--python-tool pip|uv` picks the Python installer; `uv` is used when it is on the PATH.

## Add the service's own package to a new manifest

```bash title="Terminal"
alis packages add acme.sh.orders.v1 --language node
```

This adds the service's generated contract package to its manifests. It does not add arbitrary dependencies.

## Upgrade Alis dependencies

```bash title="Terminal"
alis packages upgrade acme.sh.orders.v1
```

Every `alis.build` dependency in the service's manifests moves to its latest version. Narrow or widen the run:

| Flag | Effect |
|---|---|
| `--only <dep-pkg-id>` | Upgrade only these dependencies (dotted package ids or exact module names; repeatable). |
| `--to <version>` | Pin the single `--only` dependency at an exact version. |
| `--path <folder-or-manifest>` | Only this nested module or manifest, relative to the service (repeatable). |
| `--language <lang>` | Only one language. |
| `--all` | Every package, third-party included. |

Locations that fail roll back to their previous manifests. With `--json` the result lists `upgraded`, `unchanged` and `skipped` per dependency.

## Python runtime versions

Generated Python packages are built for protobuf 6.33 and declare `protobuf>=6.33.5` and `grpcio>=1.81.1`. Every newer protobuf runtime loads them unchanged, and the floor lets them install beside libraries that cap protobuf below 7, such as Apache Beam and TensorFlow 2.20. Shared packages a service imports, such as `alis.open.iam.v1`, carry the same floor. The packages need no setuptools at import time.

## Why not run the package manager yourself

`go get`, `go mod tidy`, `pnpm`, `pip`, `uv` and `dart` cannot reach the private Alis registries without fresh credentials. The CLI writes short-lived credentials to `~/.npmrc`, `~/.netrc` and the Dart token store before each run. A project `.npmrc` that carries its own `_authToken` for an Alis registry host overrides the user one; keep such lines out of project files and out of git.

For Swift and Xcode, `alis packages swift <pkg> -- <args>` and `alis packages xcodebuild <pkg> -- <args>` run the native tools with refreshed registry credentials, and `alis packages xcode-check` compares installed versions with Xcode's locks.

For Rust, generated crates carry prost messages and tonic gRPC clients and servers, and are served from the product's private Cargo registry. A dependency names its registry in `Cargo.toml`:

```toml title="Cargo.toml"
[dependencies]
acme-sh-orders-v1 = { version = "1.4.0", registry = "acme-sh" }
```

The CLI records where that registry is in the project's `.cargo/config.toml`, so later `cargo` commands and your editor resolve the dependency, and hands `cargo` a short-lived token through the command's environment only. No token is written to disk. Fetching a new crate version therefore goes through `alis packages`; a plain `cargo build` works once the crates are in Cargo's local cache.

## Related

- [Define your API](https://docs.alisx.com/how-to/alis-build/define-your-api.md)
- [Authorise and repair credentials](https://docs.alisx.com/how-to/alis-build/authorise-and-repair-credentials.md)