Minimal python package support by abstractedfox · Pull Request #1881 · cloudflare/agents

abstractedfox · 2026-07-06T16:43:15Z

This implements the beginning of package support for dynamic python workers. At present, it allows defining a flat list of pure Python packages as dependencies, which it installs in the dynamic worker without dependency resolution

This is the beginning of work on this feature, it's a little comment-heavy to that end and has some patterns that may not be permanent (these have generally been noted as such). As of this commit, there are tests that start to poke at this, namely the one that brings in fastapi, which currently fails due to an extension it doesn't like.

Proof of concept for package support in dynamic Python workers. As of this commit, it can retrieve an sdist with a flat layout from pypi and install it into the virtual filesystem. It doesn't do dependency resolution, so the current tests fail when attempting to import FastAPI's deps.

Used sdists before, now it uses wheels. Pre cleanup commit

changeset-bot · 2026-07-06T16:43:21Z

⚠️ No Changeset found

Latest commit: ae50567

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

This test only needs to confirm that retrieval of a hard list of pure python packages, without dependency resolution, works.

This seems to be specific to JS packages

This dependendency caused issues when working in a container, but its removal was purely for my sake This reverts commit 4f8990d.

Also makes PyprojectToml interface less stringent

These got caught by the checks done by `pnpm run check`

pkg-pr-new · 2026-07-08T18:04:05Z

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@1881

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@1881

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@1881

create-think

npm i https://pkg.pr.new/create-think@1881

hono-agents

npm i https://pkg.pr.new/hono-agents@1881

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@1881

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@1881

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@1881

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@1881

commit: ae50567

devin-ai-integration

Devin Review found 9 potential issues.

devin-ai-integration · 2026-07-08T18:36:24Z

+    for (const path of fileSystem.list()) {
+      if (path !== "pyproject.toml") {
+        const content = fileSystem.read(path);
+        if (content !== null) {
+          modules[path] = content;
+        }
+      }
+    }


🔍 Python modules output includes all filesystem files, potentially including node_modules

The Python worker path at packages/worker-bundler/src/index.ts:148-155 iterates over all files in the filesystem (except pyproject.toml) and includes them in the output modules. If a project has both package.json with npm dependencies and a Python entry point, the installed node_modules/ tree would be included in the modules output. This could result in a very large modules object being passed to the Worker Loader. Consider filtering out node_modules/ and python_modules/ metadata directories.

Was this helpful? React with 👍 or 👎 to provide feedback.

These are just files specified by the user in the createWorker call, right? So this AI review comment seems wrong.

At that point it should be those files + all the packages that were just added, so my assumption is anything that's in there would've been put there deliberately

dom96

Overall approach looks good! Left a few comments with suggestions.

CC @hoodmane @ryanking13 @threepointone for reviews too

dom96 · 2026-07-10T10:40:08Z

+    for (const path of fileSystem.list()) {
+      if (path !== "pyproject.toml") {
+        const content = fileSystem.read(path);
+        if (content !== null) {
+          modules[path] = content;
+        }
+      }
+    }


These are just files specified by the user in the createWorker call, right? So this AI review comment seems wrong.

These are already set implicitly by createWorker

ryanking13

I left a few comments, but it looks like a good starting point.

Not all of my reviews need to be addressed in this PR. Some of my comments are for FYI, as you'll eventually handle them. If you consider some of my comments as out-of-scope of this PR and would want to hand it in the follow up PRs (which is a good practice), then please add a comment about it.

ryanking13 · 2026-07-13T13:12:57Z

+      mainModule: entryPoint,
+      modules,
+      wranglerConfig: {
+        compatibilityDate: wranglerConfig?.compatibilityDate ?? "2026-01-01",


How is this default compat date selected? How does the JS worker handle this?

I recall just choosing it as an arbitrary date that I thought would work, I can put a newer one. The JS worker as in the worker that creates the dynamic worker?

Yeah, following whatever the JS worker is doing would be a good idea.

ryanking13 · 2026-07-13T13:14:39Z

+      modules,
+      wranglerConfig: {
+        compatibilityDate: wranglerConfig?.compatibilityDate ?? "2026-01-01",
+        compatibilityFlags: wranglerConfig?.compatibilityFlags ?? [


We will always need to add python_workers flag to make the worker work. So maybe we need to inject one if this flag does not exist?

As in to the user-defined compatibility flags, in the event the user passed flags that didn't include python_workers? I can add that

Actually, that should no longer be needed for Python dynamic workers. You can run python dynamic workers without that flag.

@dom96 Should I remove it?

ryanking13 · 2026-07-13T13:16:44Z

 */

 import * as semver from "semver";
+import { unzipSync } from "fflate";


We do have CompressionStream support in CF worker. fflate claims that the performance of CompressionSTream is bad in the browser, but that might not be true.

you don't need to use CompressionStream in this PR as it is an implementation detail that we can change anytime and the performance is not our concern at this point, but it would be nice to add a comment in the code why you decided to use this package and things that need to be checked (performance compared to the CompressionStream) later.

I actually only did it this way because I dryly assumed I'd need a lib for it, I'd much rather save a dependency so I'm glad you told me that

ryanking13 · 2026-07-13T13:28:22Z

+      const response = await fetchWithTimeout(
+        wheelUrl,
+        {},
+        DEFAULT_TIMEOUT_MS * 2


Just curious, why not double the DEFAULT_TIMEOUT_MS itself?

Mostly because it's not clear to me whether that would have undesirable effects elsewhere, there are other places where this function is called with the default duration. I ended up just staying with what the JS one was doing

ryanking13 · 2026-07-13T13:52:42Z

+    // Skip wheel metadata and data directories
+    if (path.includes(".dist-info/") || path.includes(".data/")) {
+      continue;
+    }


Why? These are important files used in runtime as well.

ryanking13 · 2026-07-13T13:54:26Z


+async function fetchPythonPackageMetadata(name: string, registry: string) {
+  // Fetch package metadata from PyPI JSON API
+  const metadataResponse = await fetchWithTimeout(`${registry}/${name}/json`);


This is a legacy API endpoint that only PyPI uses. There is a PEP 691 which is a standard now, so I would recommend to use that instead.

Is it easy to move to the new endpoints? Like is it just a URL change? If not we can do this in a follow up (so a TODO comment is fine here IMO)

I did end up starting this one on a separate branch, will add a todo

A little bit of URL change + json handling. You can start with this legacy api and switch to the PEP 691 one in a follow up PR (note that the Pyodide index (index.pyodide.org) does not support this endpoint)

Remove check for when there are no dependencies, since there will always be at least one

abstractedfox

Will have some more commits in for changes requested by @ryanking13, though I may want to save some of them for a future PR if that's alright

abstractedfox · 2026-07-13T16:46:53Z

+      mainModule: entryPoint,
+      modules,
+      wranglerConfig: {
+        compatibilityDate: wranglerConfig?.compatibilityDate ?? "2026-01-01",


I recall just choosing it as an arbitrary date that I thought would work, I can put a newer one. The JS worker as in the worker that creates the dynamic worker?

abstractedfox · 2026-07-13T16:46:56Z

+      modules,
+      wranglerConfig: {
+        compatibilityDate: wranglerConfig?.compatibilityDate ?? "2026-01-01",
+        compatibilityFlags: wranglerConfig?.compatibilityFlags ?? [


As in to the user-defined compatibility flags, in the event the user passed flags that didn't include python_workers? I can add that

abstractedfox · 2026-07-13T16:47:06Z

 */

 import * as semver from "semver";
+import { unzipSync } from "fflate";


I actually only did it this way because I dryly assumed I'd need a lib for it, I'd much rather save a dependency so I'm glad you told me that

abstractedfox · 2026-07-13T16:50:12Z

        installedPackages,
        inProgress,
-        registry
+        PYPI_JSON_API // hardcoding this for now to keep the implementation light


ahh thanks, that actually answers a question that was on my mind this morning. I may want to do that in an upcoming pr if that's alright with you

abstractedfox · 2026-07-13T18:19:05Z

+  }
+
+  // Skip if the package already exists in the filesystem
+  if (fileSystem.read(`python_modules/${name}/__init__.py`) !== null) {


ah, thanks for pointing that out, I realized distribution packages could have differently named packages inside them while working in another branch but I didn't change this there either (though I didn't know packages could not have __init__.py). I more or less did what the JS implementation was doing here, a snap assumption was that it was to prevent races in some way but the comment for the JS one says it's done in case installDependencies is called on a 'pre-warmed filesystem', though I don't know how often this actually happens

abstractedfox · 2026-07-13T18:24:25Z

+      const response = await fetchWithTimeout(
+        wheelUrl,
+        {},
+        DEFAULT_TIMEOUT_MS * 2


Mostly because it's not clear to me whether that would have undesirable effects elsewhere, there are other places where this function is called with the default duration. I ended up just staying with what the JS one was doing

abstractedfox · 2026-07-13T18:26:55Z

+          `No wheel distribution found for ${name}@${version} on PyPI`
+        );
+      }
+      const wheelUrl = wheel.url;


Ah thank you, I was thinking earlier about what I'd need to do about platform specific wheels

dom96

A few more comments and things that I think should be fixed before merge, but overall looks good to me so approving.

dom96 · 2026-07-14T15:27:07Z

+      modules,
+      wranglerConfig: {
+        compatibilityDate: wranglerConfig?.compatibilityDate ?? "2026-01-01",
+        compatibilityFlags: wranglerConfig?.compatibilityFlags ?? [


dom96 · 2026-07-14T16:22:02Z

+      if (path === "pyproject.toml") {
+        continue;
+      }


Is this necessary? No one is likely to be specifying pyproject.toml in the createWorker call

@dom96 This is the pyproject.toml that contains all the deps for the worker, so as far as I understand we do need to have it coming into createWorker

Ahh, my mistake, for some reason I thought pyproject.toml wasn't in the "files" dict, but one level above (same for packages.json, but I just checked and it's also in the "files" dict).

All good to leave this then.

dom96 · 2026-07-14T17:10:03Z

+  }
+
+  // Skip if the package already exists in the filesystem
+  if (fileSystem.read(`python_modules/${name}/__init__.py`) !== null) {


With @ryanking13's comment below, perhaps the best thing to do here is to just delete this and rely on the installedPackages check instead. You can add a TODO to consider doing this in the future because the JS is doing it.

dom96 · 2026-07-14T17:10:14Z

+  }
+
+  // Skip if the package already exists in the filesystem
+  if (fileSystem.read(`python_modules/${name}/__init__.py`) !== null) {


https://github.com/cloudflare/agents/pull/1881/changes#r3581110896

dom96 · 2026-07-14T17:11:38Z

+          `No wheel distribution found for ${name}@${version} on PyPI`
+        );
+      }
+      const wheelUrl = wheel.url;


I think this kind of thing can be pushed to a TODO comment and done in separate PRs. Let's iterate via follow up PRs rather than ensuring everything is 100% in this PR, especially when it comes to Python packaging details.

dom96 · 2026-07-14T17:12:52Z


+async function fetchPythonPackageMetadata(name: string, registry: string) {
+  // Fetch package metadata from PyPI JSON API
+  const metadataResponse = await fetchWithTimeout(`${registry}/${name}/json`);


Is it easy to move to the new endpoints? Like is it just a URL change? If not we can do this in a follow up (so a TODO comment is fine here IMO)

This is implicit on Python dynamic workers now

…the result object

…oml and package.json in one worker

abstractedfox

One last question in the comments but I think this is otherwise just about there!

abstractedfox · 2026-07-14T19:55:11Z

+      if (path === "pyproject.toml") {
+        continue;
+      }


@dom96 This is the pyproject.toml that contains all the deps for the worker, so as far as I understand we do need to have it coming into createWorker

abstractedfox · 2026-07-14T20:29:26Z


+async function fetchPythonPackageMetadata(name: string, registry: string) {
+  // Fetch package metadata from PyPI JSON API
+  const metadataResponse = await fetchWithTimeout(`${registry}/${name}/json`);


I did end up starting this one on a separate branch, will add a todo

ryanking13 · 2026-07-16T12:54:59Z

cc: @threepointone The python workers team doesn't seem to be possible to approve and merge this. Can you help with this?

xcaptain · 2026-07-17T03:18:58Z

So if this PR got merged, dynamic worker can be a full featured python code runner, no need to use docker based sandbox right? I don't like the docker sandbox because it's imcompatitable with vitest-pool-workers which make writing tests very hard (need to start real server to connect to docker).

ryanking13 · 2026-07-19T08:37:29Z

@xcaptain This is still experimental so the answer is yes and no. I would say you should not rely on this yet (or you can volunteer to help us debugging things :) ).

no need to use docker based sandbox right? I don't like the docker sandbox because it's imcompatitable with cloudflare/workers-sdk#10408 which make writing tests very hard (need to start real server to connect to docker).

Also, yes and no. It is true that you can use dynamic workers with Python, but it you need to run a workload that is computation / memory heavy, then it is not a good fit for worker. So it depends on your workload

abstractedfox added 7 commits June 28, 2026 00:15

remove dependency that was causing issues

4f8990d

Reconstitute work on this repo

3b8ea8f

Add index.py as default entry point

96153da

Clarifying comment

98ad2f7

Use wheels properly

e01a96e

Used sdists before, now it uses wheels. Pre cleanup commit

abstractedfox added 12 commits July 6, 2026 15:09

Wheel changeover cleanup

2fd4db5

Use simpler packages for minimal package support test

248a149

This test only needs to confirm that retrieval of a hard list of pure python packages, without dependency resolution, works.

Move python logic out of 'bundle' path

2ca7e73

This seems to be specific to JS packages

Slight cleanup, remove test

58e6874

More cleanup

1cf3db3

Re-add parameter that was mistakenly deleted

ceda163

Revert "remove dependency that was causing issues"

7244ec5

This dependendency caused issues when working in a container, but its removal was purely for my sake This reverts commit 4f8990d.

Order deps alphabetically

493cf55

Remove unused variable

4fa5fce

Make createWorker Python return more uniform with JS

bf8d3a9

Make createWorker registry pattern more consistent with JS

6b365dd

Also makes PyprojectToml interface less stringent

Small fixes

7a2a85f

These got caught by the checks done by `pnpm run check`

abstractedfox changed the title ~~Draft: Python package progress~~ Minimal python package support Jul 8, 2026

abstractedfox marked this pull request as ready for review July 8, 2026 18:32

devin-ai-integration Bot reviewed Jul 8, 2026

View reviewed changes

dom96 reviewed Jul 10, 2026

View reviewed changes

abstractedfox added 5 commits July 10, 2026 10:02

Style fixes

ecbd776

Remove parsing for version string

8016a35

Comment dep version parameter

766e58c

Compensate for distribution packages' names not matching their imports

40cbc98

Remove default values from test

f3289dc

These are already set implicitly by createWorker

abstractedfox added 3 commits July 10, 2026 13:33

Move Python package metadata collection into its own function

6fde2e0

Move Py deps installation into its own function

b711067

Account for type checker

4c56501

ryanking13 reviewed Jul 13, 2026

View reviewed changes

abstractedfox added 5 commits July 13, 2026 11:27

Undo unintended compat date change

7ade11e

Bump up compatibility date (test)

ca0ce79

Prevent adding python and JS deps to the same worker

1a68186

Implicitly add workers-runtime-sdk package

bfcdec1

Remove check for when there are no dependencies, since there will always be at least one

Add python_workers flag if user-supplied flags exclude it

58b0743

abstractedfox commented Jul 13, 2026

View reviewed changes

abstractedfox added 3 commits July 14, 2026 09:26

Typo

a088712

Clarifying comment

691e4cb

Include installWarnings with returned object

4740d96

abstractedfox mentioned this pull request Jul 14, 2026

Initial Python package resolution #1945

Draft

dom96 approved these changes Jul 14, 2026

View reviewed changes

abstractedfox added 6 commits July 14, 2026 14:35

Change tests to assert existence of compat flags

dcdd6fd

Remove redundant compat flag default

d6fd735

This is implicit on Python dynamic workers now

Mark comment as TODO

ee05c75

Change installDependenciesPython to replicate the JS impl's usage of …

75fdf12

…the result object

Finish propagating result object and explicitly disable pyproject.t…

79293af

…oml and package.json in one worker

Add more TODOs

ae50567

abstractedfox commented Jul 14, 2026

View reviewed changes

abstractedfox mentioned this pull request Jul 15, 2026

Change Python package resolution to use the PyPA simple api on PyPI #1950

Draft

abstractedfox mentioned this pull request Jul 16, 2026

Add support for the Pyodide package index #1953

Draft

abstractedfox mentioned this pull request Jul 21, 2026

Python package resolution abstractedfox/agents#4

Open

Uh oh!

Conversation

abstractedfox commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

pkg-pr-new Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

devin-ai-integration Bot Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dom96 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ryanking13 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ryanking13 Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

abstractedfox commented Jul 6, 2026 •

edited

Loading

changeset-bot Bot commented Jul 6, 2026 •

edited

Loading

pkg-pr-new Bot commented Jul 8, 2026 •

edited

Loading

ryanking13 left a comment •

edited

Loading

ryanking13 Jul 16, 2026 •

edited

Loading