Freestyleuv
Add Python runtime via uv to your VMs.
The uv integration installs Python via uv, an extremely fast Python package installer and resolver, and provides helper methods for running Python code.
If you're using uv, you don't need to also add the base Python integration. uv manages its own Python installation.
Installation
npm install @freestyle-sh/with-uv freestyle-sandboxesUsage
import { freestyle } from "freestyle-sandboxes";
import { VmUv } from "@freestyle-sh/with-uv";
const { vm } = await freestyle.vms.create({
with: {
uv: new VmUv(),
},
});
const res = await vm.uv.runCode({
code: "import json; print(json.dumps({ 'hello': 'world' }))"
});
console.log(res);
// { result: { hello: 'world' }, stdout: '{"hello": "world"}\n', statusCode: 0 }Options
new VmUv({
version: "0.5.0", // Optional: specific uv version
pythonVersion: "3.13", // Optional: Python version (default: "3.14")
})| Option | Type | Default | Description |
|---|---|---|---|
version | string | undefined | uv version to install. If not specified, installs the latest version. |
pythonVersion | string | "3.14" | Python version to install via uv. |
API
vm.uv.runCode({ code })
Executes Python code using uv's managed Python runtime.
const res = await vm.uv.runCode({
code: `
import json
data = {"sum": 1 + 2, "list": [1, 2, 3]}
print(json.dumps(data))
`
});
console.log(res.result); // { sum: 3, list: [1, 2, 3] }Returns: Promise<RunCodeResponse>
type RunCodeResponse<Result> = {
result: Result; // Parsed JSON from stdout (if valid JSON)
stdout?: string; // Raw stdout output
stderr?: string; // Raw stderr output
statusCode?: number; // Exit code
};Why uv?
uv is significantly faster than traditional Python tools:
- 10-100x faster than pip for package installation
- Built-in Python version management - no need for pyenv
- Rust-powered - fast and reliable
- Drop-in replacement for pip, pip-tools, and virtualenv
Example: Data Processing
import { freestyle } from "freestyle-sandboxes";
import { VmUv } from "@freestyle-sh/with-uv";
const { vm } = await freestyle.vms.create({
with: {
uv: new VmUv({ pythonVersion: "3.12" }),
},
});
const res = await vm.uv.runCode({
code: `
import json
numbers = [1, 2, 3, 4, 5]
result = {
"sum": sum(numbers),
"average": sum(numbers) / len(numbers),
"squared": [n ** 2 for n in numbers]
}
print(json.dumps(result))
`
});
console.log(res.result);
// { sum: 15, average: 3, squared: [1, 4, 9, 16, 25] }