Quick Start

PX makes parallel execution simple: pipe inputs to a command, and PX runs it across local CPU cores or cloud cluster nodes. Get up and running in under 5 minutes. This guide walks through installing PX, running your first parallel job locally, then scaling the same job out to a cloud cluster.

Prerequisites

• uv (used to install PX)
• A cloud account (only for the cloud steps). GCP supported during private beta; AWS, Azure, and DigitalOcean coming soon.
• Basic familiarity with the command line

Step 1: Install PX

Install PX with uv tool.

Latest stable release (recommended):

uv tool install --force --no-cache --from https://px.app/releases/latest/px.tar.gz px

Tip build (latest commits on main; may include breakage):

uv tool install --force --no-cache --from https://px.app/releases/nightly/latest/px.tar.gz px

Why uv and these flags?

During the private beta, PX CLI releases are managed manually and we use uv tool to pull in third-party dependencies that the px tool needs.

--force --no-cache ensures you always get the latest tarball. Without these, uv may reuse a previously downloaded copy and miss a fresh upstream build.

For more on uv, see the uv documentation.

Verify the install:

px --version

Step 2: Run a Parallel Job Locally

Pipe a sequence of inputs into px run. Each input becomes one task argument; PX partitions them across parallel tasks.

seq 1 16 | px run -p 4 'while read line; do echo "pid=$$ arg=$line"; done'

You'll see output like:

[px] Supervisor loaded
[px]   cmd: while read line; do echo "pid=$$ arg=$line"; done
[px]   args: *via stdin
[px]   parallelism: 4
[px] ---
[px] Creating input stream...
[px] Partitioning inputs for tasks...
[px] ---
[px] Start: task=0
[px] Start: task=1
[px] Start: task=2
[px] Start: task=3
pid=2698278 arg=2
pid=2698278 arg=6
pid=2698278 arg=10
pid=2698278 arg=14
pid=2698277 arg=1
pid=2698277 arg=5
pid=2698277 arg=9
pid=2698277 arg=13
[px] Stop: task=0
[px] Stop: task=1
pid=2698280 arg=4
pid=2698280 arg=8
pid=2698280 arg=12
pid=2698280 arg=16
pid=2698279 arg=3
pid=2698279 arg=7
pid=2698279 arg=11
pid=2698279 arg=15
[px] Stop: task=2
[px] Stop: task=3

What this command did:

• Spawned 4 tasks
• Partitioned the 16 input lines across them (4 lines per task)
• Each task printed its PID alongside the argument it processed

Any program, any language

The command between quotes is just a shell command. PX supports any programming language for user code, including Python, Ruby, JavaScript, TypeScript, Rust, Zig, C/C++, Go, Java, and more. For end-to-end walkthroughs, see px-systems/examples.

Step 3: Authenticate with Your Cloud

To run the same job on a cluster, PX needs access to your cloud provider.

px cloud login gcp

Your browser will open to authenticate with GCP:

Authenticating with gcp...
Your browser has been opened to visit:

    https://accounts.google.com/o/oauth2/auth?...

Follow the prompts. PX will securely store your credentials for future use.

Where are credentials stored?

Your Google Cloud credentials are stored in ~/.config/gcloud/ using the standard Google Cloud CLI configuration. PX uses these credentials to provision and manage cloud resources on your behalf.

Set your GCP project

List your projects with gcloud projects list and activate one with gcloud config set project <PROJECT_ID>.

Step 4: Generate a Cluster Spec

Generate a starter px.yaml for your cluster:

px cluster generate-config

This drops a fully-commented px.yaml.example in the current directory. Copy it to px.yaml. For this Quickstart, the defaults are fine; the minimal shape looks like:

num_nodes: 3

resources:
  infra: gcp/us-central1
  cpus: 2
  use_spot: true
  ports:
    - 8020

px.yaml is a SkyPilot subset

px.yaml is a curated subset of the SkyPilot task YAML spec. The generated px.yaml.example documents every supported field; don't memorize the schema, just edit the template. For the full reference, see px.yaml.

Step 5: Bring Up the Cluster

px cluster up my-cluster

Provisioning cluster 'my-cluster' (px.yaml)...
Considered resources (3 nodes):
------------------------------------------------------------------------------------------
INFRA                 INSTANCE              vCPUs   Mem(GB)   GPUS   COST ($)   CHOSEN
------------------------------------------------------------------------------------------
GCP (us-central1-a)   n4-standard-2[Spot]   2       8         -      0.11          ✔
------------------------------------------------------------------------------------------
Launching on GCP us-central1 (us-central1-a)
✓ Instances launched
✓ Workdir synced        ~/sky_logs/sky-2026-05-07-14-43-29-212699/workdir_sync.log
✓ Storage mounted       ~/sky_logs/sky-2026-05-07-14-43-29-212699/storage_mounts.log
✓ Setup completed
✓ PX runtime ready

Cloud econometric model

PX uses a real-time pricing database to pick the cheapest spot instance that meets your resources constraints. The "Considered resources" table shows what was evaluated and which option was chosen.

Inspect what you just provisioned:

px cluster status my-cluster

ID            = e7d03c40-f129-40f1-9692-8cec9c6d6135
Name          = my-cluster
Name On Cloud = my-cluster-267fc313
Status        = up
Infra         = gcp
Region        = us-central1
Spec File     = /home/user/.sky/generated/my-cluster.yml
Created       = May 07, 12:47 UTC
Duration      = 12m

Resources
Instance   = n4-standard-2 [Spot]
CPUs       = 2.0 (per node)
Disk       = 100GB (low tier)
Ports      = 8020
Node Count = 3

Head Node
Hostname   = my-cluster
Public IP  = 35.222.23.86
Private IP = 10.128.0.37

Worker Nodes
Hostname            Public IP      Private IP
my-cluster-worker1  34.56.115.68   10.128.0.35
my-cluster-worker2  34.63.192.212  10.128.0.36

Cost
Hourly = $0.11
Total  = $0.02

Step 6: Submit the Same Job to the Cluster

Same pipeline, now running across cloud nodes:

seq 1 16 | px job submit -c my-cluster -p 4 'while read line; do echo "pid=$$ arg=$line"; done'

[px] Running command in cluster mode
[px]   cluster: my-cluster
[px]   parallelism: 4
[px]   job_id: e9665b5032c5
[px] ---
[px] Logs will stream here. Pressing Ctrl-C will stop streaming,
[px] but will not stop the job running remotely.

[stdout] [px] Supervisor loaded
[stdout] [px]   cmd: while read line; do echo "pid=$$ arg=$line"; done
[stdout] [px]   args: *via stdin
[stdout] [px]   parallelism: 2
[stdout] [px] ---
[stdout] [px] Creating input stream...
[stdout] [px] Partitioning inputs for tasks...
[stdout] [px] ---
[stdout] [px] Start: task=0
[stdout] [px] Start: task=1
[stdout] pid=7611 arg=1
[stdout] pid=7611 arg=3
[stdout] pid=7611 arg=5
[stdout] pid=7611 arg=7
[stdout] pid=7611 arg=9
[stdout] pid=7613 arg=2
[stdout] pid=7613 arg=4
[stdout] pid=7613 arg=6
[stdout] pid=7613 arg=8
[stdout] pid=7613 arg=10
[stdout] [px] Stop: task=0
[stdout] [px] Stop: task=1
[stdout] [px] Supervisor loaded
[stdout] [px]   cmd: while read line; do echo "pid=$$ arg=$line"; done
[stdout] [px]   args: *via stdin
[stdout] [px]   parallelism: 2
[stdout] [px] ---
[stdout] [px] Creating input stream...
[stdout] [px] Partitioning inputs for tasks...
[stdout] [px] ---
[stdout] [px] Start: task=0
[stdout] [px] Start: task=1
[stdout] pid=7688 arg=11
[stdout] pid=7688 arg=13
[stdout] pid=7688 arg=15
[stdout] pid=7690 arg=12
[stdout] pid=7690 arg=14
[stdout] pid=7690 arg=16
[stdout] [px] Stop: task=0
[stdout] [px] Stop: task=1

[px] Job completed

Why does each worker show parallelism: 2?

You asked for -p 4 total parallelism. PX divides that across the 2 workers in your cluster, giving 2 parallel tasks per worker. The full banner prints once per worker because each worker runs its own local supervisor.

[stdout] and [stderr] prefixes appear because px job submit streams both channels by default; pass --stream stdout or --stream stderr to filter.

Step 7: Inspect Jobs

List jobs on the cluster:

px job ls -c my-cluster

JOB_ID        COMMAND                                            STATUS     PROGRESS  PARALLELISM  CREATED
e9665b5032c5  while read line; do echo "pid=$$ arg=$line"; done  completed  100.0%    4            3m ago

Drill into one:

px job status -c my-cluster e9665b5032c5

ID          = e9665b5032c5
Command     = while read line; do echo "pid=$$ arg=$line"; done
Parallelism = 4
Status      = completed
Created     = May 07, 12:51 UTC
Started     = May 07, 12:51 UTC
Completed   = May 07, 12:51 UTC

Progress
Total Args = 16
Processed  = 16
Failed     = 0
Progress   = 100.0%

To re-stream the logs of a completed (or live) job, use px job logs -c my-cluster <job_id>.

Step 8: Tear Down

When you're done, terminate the cluster to stop billing:

px cluster down my-cluster

Terminating cluster my-cluster...
✓ Cluster terminated

Next Steps

• For all available commands and flags, see the CLI Reference.
• For the full px.yaml schema, see the px.yaml reference.
• For a deeper look at how PX partitions and distributes work, see Parallel Execution.
• For the cluster storage model and supported providers, see Cloud Integration.
• For tips on debugging parallel jobs, see Debugging.
• For end-to-end walkthroughs (Python, image processing, cloud storage, and more), see px-systems/examples.