awesome-python-dev has two independently versioned layers. The npm shell provides the command entry point and runtime loader. The Python runtime contains the installer, agent adapters, catalog, rules support and locked dependencies. The current shell is 0.1.1 and the runtime is 0.3.0. Runtime updates do not require a new npm version.

Package sizes are approximate and change with content. The zipapp includes tomlkit, catalog data, dependency metadata and licenses; it does not include the Python interpreter or download upstream skills in advance.

The npm entry point requires Node.js 22.21+ (22.x) or 24.5+ and Python 3.11+ or uv:

npx awesome-python-dev init --agents codex,claude --profile starter

For repeated use:

npm install --global awesome-python-dev
apd init --agents codex,claude --profile fastapi --dry-run
apd init --agents codex,claude --profile fastapi

Use these commands inside the project you want to equip. When Python is not available but uv is installed, uv can provision Python 3.13. The shell does not install uv itself. Selected MCP servers may have additional prerequisites.

The Python distribution offers a separate, shorter Python-native route:

uvx awesome-python-dev init --agents codex,claude --profile starter
uv tool install awesome-python-dev

Choose one global installation method: both provide apd and awesome-python-dev. A PyPI installation follows uv's package version and upgrade behavior; it does not use the npm shell's runtime channel, cache or runtime subcommands. Upgrade it with uv tool upgrade awesome-python-dev, or use uvx awesome-python-dev@latest for a fresh latest-version invocation.

apd --shell-version
apd --version
apd runtime status
apd runtime update

--shell-version prints the npm package version without network access. --version launches the selected runtime and prints its version. runtime status reads local selection and cache information without downloading files. runtime update checks the stable channel immediately unless a version is selected through APD_RUNTIME_VERSION.

On normal invocations, the shell checks the compatible stable channel at most once every 24 hours. The channel is the runtime.json asset on the runtime-v1 GitHub Release. It points to an immutable versioned asset such as v0.3.0/awesome-python-dev-runtime-0.3.0.pyz. The channel release is marked as a prerelease to keep it separate from the project's normal latest release.

The loader validates the manifest, downloads the runtime if needed, checks its size and SHA-256, and writes cache files atomically. It verifies the cached runtime again before every launch. A failed network refresh can use a previously verified stable runtime. An invalid manifest or checksum fails closed. The npm package's embedded bootstrap manifest supplies a known version if the channel is unreachable; first use still needs access to that runtime asset.

Runtime code downloads happen on first use, not during npm install. The package has no postinstall hook or npm runtime dependencies. Arguments and working directory pass through to the Python CLI.

The launcher honors HTTP_PROXY, HTTPS_PROXY and NO_PROXY, including their lowercase forms, using Node's built-in proxy support. This applies to both manifest and runtime asset downloads. Set NODE_USE_ENV_PROXY=0 to explicitly disable this behavior. The launcher does not change system or shell settings.

For a local HTTP proxy, export its actual address before invoking the CLI:

export HTTPS_PROXY=http://127.0.0.1:7897
npx awesome-python-dev --version

Use the HTTP endpoint provided by your proxy. A macOS system proxy setting or ALL_PROXY alone does not configure Node's built-in HTTP proxy support.

apd runtime update 0.3.0
APD_RUNTIME_VERSION=0.3.0 apd list
APD_RUNTIME_VERSION=0.3.0 apd init --agents codex --profile python --dry-run

runtime update VERSION downloads and verifies that exact version. It does not permanently switch the default stable selection. Set APD_RUNTIME_VERSION to select the version on subsequent commands. Exact pins never fall back to a different runtime. Unset the variable to resume the stable channel.

For PowerShell:

$env:APD_RUNTIME_VERSION = '0.3.0'
apd list
Remove-Item Env:APD_RUNTIME_VERSION

Default runtime cache locations are:

• macOS: ~/Library/Caches/awesome-python-dev
• Linux: $XDG_CACHE_HOME/awesome-python-dev, or ~/.cache/awesome-python-dev
• Windows: %LOCALAPPDATA%\awesome-python-dev

After caching a version, it can launch offline:

APD_RUNTIME_VERSION=0.3.0 APD_OFFLINE=1 apd list

Offline mode also disables uv network access and Python downloads when uv is used. It does not make installation of uncached upstream skills, rules or MCP dependencies work offline. The runtime cache is separate from the npm installation and the project's .awesome-python-dev ownership records. Deleting the user runtime cache reclaims space; the next online invocation downloads the selected runtime again.

The loader accepts protocol-1 manifests and restricts download URLs to this project's GitHub Releases, with bounded HTTPS redirects, timeouts and sizes. SHA-256 verifies integrity against the manifest. It is not an independent signature: the repository's release maintainers and npm publisher remain trust sources. See the security model.

New runtime releases keep protocol 1 while compatible with existing shells. A future incompatible protocol requires a new shell release and its own channel; older shells must not silently execute an unsupported manifest. Follow the release guide to publish runtime and shell changes separately.