Migrating from cowboy-sdk 0.1

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 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

Replace the requirement. In pyproject.toml, change cowboy-sdk to cowboy-actor-sdk:
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.
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:
[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.
Regenerate the lock and sync the environment:
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 instead: pip doesn’t remove packages that you drop from a requirements file.

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.

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. For other environments, activate the intended environment and use its Python to list the distributions that register cowboy_sdk:

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 instead of the commands below: a plain install does not restore deleted files when the distribution is already registered.

pip
uv pip

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"

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

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.

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; 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.

pip
uv pip
uv project

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"

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"

# 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
`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: if it lists `cowboy-actor-sdk`, Repair. Otherwise update the requirement as in 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
`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
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

For the Actor SDK’s features and testing tools, see the SDK overview and Testing Actors.

Start Here

Build

How Cowboy Works

Reference

Migrating from cowboy-sdk 0.1

Who this is for

What changed

Update your project

Stopgap: pin `cowboy-sdk<0.2`

Migrate an existing environment

Check your environment

Repair a broken environment

Troubleshooting

​Who this is for

​What changed

​Update your project

​Stopgap: pin cowboy-sdk<0.2

​Migrate an existing environment

​Check your environment

​Repair a broken environment

​Troubleshooting

Who this is for

What changed

Update your project

Stopgap: pin `cowboy-sdk<0.2`

Migrate an existing environment

Check your environment

Repair a broken environment

Troubleshooting