The Ape Framework ships as eth-ape, and its own Docker recipe names a file the repository does not carry

The package is eth-ape and the repository is called ape

The repository, the command and the distribution are three different names. The repository is ApeWorX/ape, the command you run is ape, and the thing you install from PyPI is eth-ape. Anyone following the quickstart by typing the repository name into a package manager will get nothing, because the install line is pipx install eth-ape or pip install eth-ape.

Three routes are offered, and the write-up attaches advice to each. For pip users it advises the most up-to-date pip, with a link to issue 1558 as the reason and pip install --upgrade pip as the remedy. It advises a virtualenv or venv so the install does not interfere with OS-level site packages, and it tells macOS users to install virtualenv through homebrew. For the plugin set it recommends the extra rather than the bare package:

pip install eth-ape'[recommended-plugins]'

That distinction carries further than the install line. The recommended-plugins extra is what the container images are built with, and the documented container run command explicitly requires the full install that includes it, so the slim image and the plugin-free install are a matched pair rather than two ways of doing the same thing.

One detail is worth carrying forward before anything else: after installing, the quickstart verifies with ape --version, and everything past that point, accounts, networks, projects, compiling, testing, the console, scripting and logging, lives in the documentation site rather than in this file.

Windows needs WSL in the docs and a native classifier in the metadata

The prerequisite section is short and unambiguous: Linux or macOS, Python 3.10 up to 3.13, and on Windows an installation of the Windows Subsystem for Linux. There is no native Windows path in the documentation, and the file even tells you to check your interpreter with python3 --version first.

The packaging metadata says something looser. The classifier list includes Operating System :: Microsoft :: Windows alongside MacOS and POSIX, and requires-python is >=3.10,<4, an open-ended range. The same classifier list runs Python 3.10, 3.11, 3.12, 3.13 and then 3.14, while the prerequisite text stops at 3.13. So a Windows user reading the package index sees a supported Windows classifier, and a Python 3.14 user sees a 3.14 classifier, in a project whose own documentation lists neither.

That gap is not fatal, and it may simply reflect testing that outran a documentation edit. It does mean the index is not a reliable summary of the support matrix. For planning purposes, treat the prerequisite section as the contract and the classifiers as aspiration, and if you need either Windows natively or Python 3.14, confirm against the project before committing.

Two container images, and the slim build recipe names a missing file

Images are published on ghcr, in two flavours:

$ docker pull ghcr.io/apeworx/ape:latest  # installs with recommended-plugins
$ docker pull ghcr.io/apeworx/ape:latest-slim  # installs ape with required packages

The default image is built with the recommended-plugins extra and is described as a good starting point for a containerized environment. The slim image is built without any installed plugins, is meant for production support, and must be configured further if any plugin is in use. The two comments are also slightly at odds, since one calls the slim image an install with required packages while the prose calls it a build with no plugins at all.

Building locally is where the documentation and the repository disagree:

$ docker build -t ape:latest-slim -f Dockerfile.slim .
$ docker build -t ape:latest .

The repository root carries a single Dockerfile. Dockerfile.slim, named in the first of those two lines, is not among the top-level entries, so that command cannot succeed from a fresh clone of this tree. Note also that three different reference forms appear in one section: ghcr.io/apeworx/ape:latest for pulling, ape:latest and ape:latest-slim for locally built tags, and the bare apeworx/ape used to run:

docker run \
  --volume $HOME/.ape:/home/harambe/.ape \
  --volume $HOME/.vvm:/home/harambe/.vvm \
  --volume $HOME/.solcx:/home/harambe/.solcx \
  --volume $PWD:/home/harambe/project \
  apeworx/ape compile

That run example mounts the Ape configuration directory, the Vyper compiler cache and the solc compiler cache into a fixed container user whose home is /home/harambe. It also requires the full install with recommended-plugins, which is why the note under it exists.

The container build freezes a lockfile the repository does not carry

The committed Dockerfile is a two-stage build driven by uv. It copies the binary from ghcr.io/astral-sh/uv:latest, sets WORKDIR to /home/harambe/project, copies only pyproject.toml and uv.lock, and then turns on a run of UV_ variables: UV_MANAGED_PYTHON=false, UV_NO_DEV=true, UV_FROZEN=true, UV_NO_EDITABLE=true, UV_COMPILE_BYTECODE=true and UV_LINK_MODE=copy. The dependency install is a single uv sync --no-install-project behind a cache mount, and the version is mocked for setuptools-scm through SETUPTOOLS_SCM_PRETEND_VERSION_FOR_ETH_APE because the project declares a dynamic version and a git checkout has no tag to read.

Two things in that sequence do not line up with the repository. First, uv.lock is not among the top-level entries, and the Dockerfile's own comment says that in CI you need to cache uv.lock or create it if it does not exist. Creating a lockfile is at odds with UV_FROZEN=true, which asks uv to refuse anything that would change the lock. Second, uv itself is pulled at :latest, so the tool that resolves the build is not pinned even though everything it resolves is.

None of this affects a pip or pipx install, which never touches the container recipe. It matters if you plan to build images yourself, because the path that looks most reproducible, a frozen lock, is the one with the missing input.

pytest and pluggy are install requirements, not development ones

The dependency list carries the test framework in the install path. pytest>=8.0,<9.0 and pluggy>=1.3,<2 both sit in project dependencies rather than in an optional group, so anyone who installs eth-ape installs pytest and its plugin machinery whether or not they intend to run a test suite. ipython>=8.18.1,<9 is there too, which is what backs the Ape console, and click is held to a narrow band at >=8.1.6,<8.2 while most other entries are allowed a full major version.

The reasons for the range choices are not uniform, and where they exist they are written down as comments next to the requirement. asttokens>=2.4.1,<3 carries the note that it is a peer dependency and that without the pin the container build fails. numpy is held below 2 with the comment that NumPy 2.0 causes issues for some users, while pandas is allowed the wider >=2.2.2,<3.

That numpy decision is the one to understand before upgrading anything around it. It is a deliberate choice with a stated cause rather than an oversight, and it means a project that installs Ape is pinned to the NumPy 1.x line, which constrains what else can share the environment. The rest of the list is more conventional: ijson, lazyasd, cchecksum, packaging, pydantic with pydantic-settings, python-dateutil and PyYAML, all with upper bounds on the next major version.

A plugin from outside the organization gets a warning, not a block

The plugin system is the reason the framework can claim support for several contract languages and chains, and the file treats third-party code as a decision the user makes consciously. Plugins that do not originate from the ApeWorX GitHub organization produce a warning at install time, followed by the sentence that they should be installed at your own risk. There is no allowlist, no signature check and no permission prompt described, so the warning is the entire mechanism.

What that means in practice depends on what a plugin is. Ape plugins supply contract languages, networks, accounts and tooling, which means a third-party plugin can add code that compiles and deploys contracts and reads whatever credentials the session holds. The warning tells you the project will not stand behind it; it does not enumerate what the plugin can reach.

Two guides are offered for the other half of the story, one on installing plugins and one on developing your own, and there are two separate documentation properties: a technical documentation site at docs.apeworx.io and a separate academy at academy.apeworx.io with tutorials and challenges. The user guides it points at from here cover accounts, networks, projects, compiling, testing, the console, scripting and logging, which is also the closest thing in this repository to a table of contents for the tool itself.

Three tags in five months, with the classifier claiming production stability

The release history is uneven. v0.8.50 shipped on 2026-05-08, v0.8.51 on 2026-08-22 and v0.8.52 on 2026-09-25, so two of the three visible tags are three months apart and the third follows a month later. The last push to the repository was on 2026-09-25 and the repository is not archived. The version itself is not written into the manifest at all, since the project declares a dynamic version and lets setuptools-scm derive it from tags, which is also why the container build has to pretend a version at build time.

The classifier Development Status :: 5 - Production/Stable sits alongside that history. It is a PyPI-facing declaration about maturity rather than a statement about how often releases land, and the 0.x version prefix alongside it is the usual signal that interfaces may still move.

The rest of the root is small and conventional: a Dockerfile, a pyproject.toml, src/ and tests/, docs/, a pre-commit configuration, a codeql-config.yml, a funding.json, CONTRIBUTING.md and the licence file. Nothing in the tree suggests the plugin registry, the network definitions or the account handling lives here, which is consistent with a framework whose real content is distributed as separate packages and whose documentation is hosted elsewhere.

Editorial conclusion

Ape is worth adopting if you want one command-line session that compiles, tests and talks to contracts across chains, and if you are on Linux or macOS with Python between 3.10 and 3.13. Verify three things before you build around it. The Windows story is WSL, not a native install, whatever the packaging classifier suggests. The local slim image build cannot work from a fresh clone, because the documented command names a Dockerfile.slim that the repository root does not contain and the Docker build freezes a uv.lock that is not committed either. And if you install plugins from outside the ApeWorX organization, you are taking on the maintenance risk yourself, because the install-time warning says exactly that and nothing in the warning describes what the plugin will touch.

Frequently asked questions

Official sources

1. ApeWorX/ape on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases