> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cowboy.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating from cowboy-sdk 0.1

> Move Actor projects and Python environments from cowboy-sdk 0.1.x to cowboy-actor-sdk, and repair environments the switch has broken

## Who this is for

Follow this guide if either of these applies to you:

* Your project requires `cowboy-sdk` for Actor code. Cowboy CLI releases `cli-v0.0.37` to `cli-v0.0.39` generate `dependencies = ["cowboy-sdk>=0.1.2"]` in `pyproject.toml`.
* A Python environment you use has the historical Actor package installed: `cowboy-sdk` 0.1.0 or 0.1.1 from PyPI, or a locally built Actor SDK 0.1.2. Use the package check in [Migrate an existing environment](#migrate-an-existing-environment) to identify it.

Projects generated by `cli-v0.0.40` or later already require `cowboy-actor-sdk` and need no changes.

## What changed

The Actor SDK is now published as **`cowboy-actor-sdk`**. The name `cowboy-sdk` belongs to the client SDK from version 0.2.0 onward.

| Package | Import | What it is |
| - | - | - |
| `cowboy-actor-sdk` 0.1.2 and later | `cowboy_sdk` | The Actor SDK: write and test Actors |
| `cowboy-sdk` 0.1.0 and 0.1.1 | `cowboy_sdk` | Historical releases of the Actor SDK, replaced by `cowboy-actor-sdk` |
| `cowboy-sdk` 0.2.0 and later | `cowboy` | The client SDK: talk to a Cowboy node from Python |

* **Actor code doesn't change.** It still imports `cowboy_sdk`, for example `from cowboy_sdk import actor, public`.
* **Deployed Actors are unaffected.** On chain, Actors run the PVM's own copy of the SDK, not a package installed from PyPI. Nothing needs to be redeployed.
* **Requirements must change.** Once `cowboy-sdk` 0.2.0 is published, a requirement such as `cowboy-sdk>=0.1.2` resolves to the client, which has no `cowboy_sdk` module.

The order in which you switch an existing environment matters. Both Actor packages install their files into the same `cowboy_sdk/` directory, and pip and uv track those files per package. If `cowboy-actor-sdk` is installed while `cowboy-sdk` 0.1.x is still present, later removing or upgrading `cowboy-sdk` deletes the files the two share, including `cowboy_sdk/__init__.py`. Neither tool reports an error when this happens.

## Update your project

1. **Replace the requirement.** In `pyproject.toml`, change `cowboy-sdk` to `cowboy-actor-sdk`:

   ```toml theme={null}
   dependencies = ["cowboy-actor-sdk>=0.1.2"]
   ```

   Make the same change wherever else you install the Actor SDK, such as requirements files, CI workflows and Dockerfiles. If the project also uses the client SDK (`import cowboy`), require it separately as `cowboy-sdk>=0.2` once `cowboy-sdk` 0.2.0 is published; until then that requirement can't be resolved. Without that lower bound, a resolver can pick 0.1.1, the historical Actor release.

2. **Remove the old source override.** Older CLIs told you to point uv at a local SDK build because the SDK wasn't on PyPI yet. Delete that block:

   ```toml theme={null}
   [tool.uv.sources]
   cowboy-sdk = { path = "/absolute/path/to/cowboy_sdk-0.1.2-py3-none-any.whl" }
   ```

   `cowboy-actor-sdk` is installed from PyPI and needs no override. Keep one only if you deliberately test an unreleased SDK build; its key is then `cowboy-actor-sdk`.

3. **Regenerate the lock and sync the environment:**

   ```bash theme={null}
   uv lock
   uv sync --reinstall-package cowboy-actor-sdk
   uv run python -c "from cowboy_sdk import codec, testing, public"
   ```

   `--reinstall-package` restores any shared files that removing `cowboy-sdk` deletes, so this is safe even if both packages were installed. The last command prints nothing when the environment is healthy. Commit `pyproject.toml` and `uv.lock` once they no longer contain a machine-specific source override or path.

   If you install with pip from a requirements file, follow [Migrate an existing environment](#migrate-an-existing-environment) instead: pip doesn't remove packages that you drop from a requirements file.

> [!WARNING]
>
> Make the change as one edit: running `uv add cowboy-actor-sdk` and then `uv remove cowboy-sdk` deletes the shared files. If you already did, run the [repair](#repair-a-broken-environment).

### Stopgap: pin `cowboy-sdk<0.2`

If you can't migrate yet, change the requirement to `cowboy-sdk<0.2` so that the 0.2.0 client is never selected. With the old `[tool.uv.sources]` override still in place, uv keeps installing your local file. This is not a fix:

* From PyPI, `cowboy-sdk<0.2` installs 0.1.1. That release has no `cowboy_sdk.testing` module and no `public` decorator, so Actors and tests generated by the CLI fail to import.
* It keeps the historical package in your environment. Installing the client later replaces it. Never require `cowboy-actor-sdk` alongside it: overlapping files can break imports immediately, and removing either package can delete files the other needs.
* New Actor SDK releases are published only as `cowboy-actor-sdk`.

## Migrate an existing environment

For a uv project, follow [Update your project](#update-your-project). For other environments, activate the intended environment and use its Python to list the distributions that register `cowboy_sdk`:

```bash theme={null}
python -c "from importlib.metadata import packages_distributions; print(packages_distributions().get('cowboy_sdk', []))"
```

If the list includes `cowboy-sdk`, remove that historical Actor distribution **before** installing `cowboy-actor-sdk`; otherwise, skip the uninstall. Older source-installed clients can also report version 0.1.0, but register `cowboy` instead and should remain installed.

If the list includes `cowboy-actor-sdk`, use [Repair a broken environment](#repair-a-broken-environment) instead of the commands below: a plain install does not restore deleted files when the distribution is already registered.

> [tab] pip
>
> ```bash theme={null}
> pip uninstall -y cowboy-sdk         # only if the package check lists cowboy-sdk
> pip install cowboy-actor-sdk
> pip install "cowboy-sdk>=0.2"       # optional: the client SDK, once 0.2.0 is published
> python -c "from cowboy_sdk import codec, testing, public"
> ```

> [tab] uv pip
>
> ```bash theme={null}
> uv pip uninstall cowboy-sdk         # only if the package check lists cowboy-sdk
> uv pip install cowboy-actor-sdk
> uv pip install "cowboy-sdk>=0.2"    # optional: the client SDK, once 0.2.0 is published
> python -c "from cowboy_sdk import codec, testing, public"
> ```

Never run `pip install --upgrade cowboy-sdk` in an environment that has the historical Actor package installed. Once `cowboy-sdk` 0.2.0 is published, the upgrade uninstalls 0.1.x, which deletes the Actor SDK's files, and installs the client.

## Check your environment

```bash theme={null}
python -c "from cowboy_sdk import codec, testing, public"
```

No output means the Actor SDK is installed correctly. In a uv project, run `uv run python -c "from cowboy_sdk import codec, testing, public"`. Each name catches a different broken state: `codec` fails when shared files have been deleted, `testing` fails when only the published 0.1.0 or 0.1.1 is installed, and `public` fails when one of those published releases has overwritten the Actor SDK.

> [!WARNING]
>
> `pip check` and `uv pip check` won't detect these problems. They compare version requirements, not the files on disk, and report no issues even when `cowboy_sdk/__init__.py` has been deleted.

`pip list` also keeps showing `cowboy-actor-sdk` in a broken environment, so use the import check above.

## Repair a broken environment

These commands repair every broken state described on this page. In the pip and uv pip tabs, first run the package check in [Migrate an existing environment](#migrate-an-existing-environment); uninstall `cowboy-sdk` only if it is listed, then reinstall `cowboy-actor-sdk` even if it is already listed. If you want the client SDK and `cowboy-sdk` 0.2.0 is published, install `cowboy-sdk>=0.2` after the uninstall and before the reinstall.

> [tab] pip
>
> ```bash theme={null}
> pip uninstall -y cowboy-sdk         # only if the package check lists cowboy-sdk
> pip install --force-reinstall --no-deps cowboy-actor-sdk
> python -c "from cowboy_sdk import codec, testing, public"
> ```

> [tab] uv pip
>
> ```bash theme={null}
> uv pip uninstall cowboy-sdk         # only if the package check lists cowboy-sdk
> uv pip install --reinstall --no-deps cowboy-actor-sdk
> python -c "from cowboy_sdk import codec, testing, public"
> ```

> [tab] uv project
>
> ```bash theme={null}
> # First update pyproject.toml so it no longer requires cowboy-sdk 0.1.x
> uv lock
> uv sync --reinstall-package cowboy-actor-sdk
> uv run python -c "from cowboy_sdk import codec, testing, public"
> ```

The forced reinstall writes every `cowboy_sdk/` file again from `cowboy-actor-sdk`. `--no-deps` leaves the Actor SDK's dependencies alone; if `pip check` then reports a missing requirement such as `cbor2`, run `pip install cowboy-actor-sdk`.

## Troubleshooting

| Error | Cause | Fix |
| - | - | - |
| `ImportError: cannot import name 'codec' from 'cowboy_sdk' (unknown location)` | `cowboy-sdk` 0.1.x was removed after `cowboy-actor-sdk` was installed alongside it, by an uninstall, `pip install --upgrade cowboy-sdk`, `uv remove cowboy-sdk` or `uv sync`. The shared files are gone, including `cowboy_sdk/__init__.py`, so Python treats `cowboy_sdk` as a namespace package. The name in the message is the first one your code imports, such as `actor`. If removal deletes the whole package directory, the error is `ModuleNotFoundError: No module named 'cowboy_sdk'` instead (next row). | [Repair](#repair-a-broken-environment) |
| `ModuleNotFoundError: No module named 'cowboy_sdk'` | The Actor SDK's files are absent. Typically `pip install --upgrade cowboy-sdk` replaced 0.1.x with the client SDK, or the project's `cowboy-sdk` requirement resolved to the client. Removing an overlapping historical package can also delete the whole directory while leaving `cowboy-actor-sdk` listed; a plain `pip install cowboy-actor-sdk` then prints `Requirement already satisfied` and restores nothing. | Run the [package check](#migrate-an-existing-environment): if it lists `cowboy-actor-sdk`, [Repair](#repair-a-broken-environment). Otherwise update the requirement as in [Update your project](#update-your-project), or run `pip install cowboy-actor-sdk` |
| `ImportError: cannot import name 'public' from 'cowboy_sdk' (…/site-packages/cowboy_sdk/__init__.py)`, or the same for `deferred`, `OWNER`, `callable_by` or another newer name | The files of `cowboy-sdk` 0.1.x are in place: either it's the only Actor package installed, or it was installed after `cowboy-actor-sdk` (for example by an old pin or an unpinned `pip install cowboy-sdk`) and overwrote the shared files. | [Repair](#repair-a-broken-environment) |
| `ImportError: cannot import name 'testing' from 'cowboy_sdk' (…/site-packages/cowboy_sdk/__init__.py)` `ModuleNotFoundError: No module named 'cowboy_sdk.testing'` | Only the published `cowboy-sdk` 0.1.0 or 0.1.1 is installed; `SimulatedChain` and the rest of `cowboy_sdk.testing` arrived in the Actor SDK later. | [Migrate the environment](#migrate-an-existing-environment) |
| uv: `No solution found when resolving dependencies` … `your project depends on cowboy-sdk>=0.1.2` pip: `ERROR: Could not find a version that satisfies the requirement cowboy-sdk>=0.1.2 (from versions: 0.1.0, 0.1.1)` | The project was generated by `cli-v0.0.37` to `cli-v0.0.39` and has no source override. No Actor SDK 0.1.2 was ever published as `cowboy-sdk`. Once the 0.2.0 client is published, the requirement resolves to it and you get `No module named 'cowboy_sdk'` instead. | [Update your project](#update-your-project) |

For the Actor SDK's features and testing tools, see the [SDK overview](https://docs.cowboy.inc/developers/sdk.md) and [Testing Actors](https://docs.cowboy.inc/developers/testing-actors.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.