Actor Build

An Apify Actor Build is the process of packaging an actor's source code, dependencies, and configuration into a versioned, immutable Docker image on the Apify platform. When you run apify push from the CLI or trigger a build via the API, Apify pulls your source code (from a direct upload, a connected GitHub/GitLab repository, or a zip archive), runs the Dockerfile instructions to install dependencies and compile code, and stores the resulting image as a numbered build version (e.g., 0.1.1, 0.2.0). Each build is immutable — once created, it cannot be modified, only superseded by a new build. Actor builds matter because they are the deployable unit on Apify. When a user runs your actor, Apify launches a Docker container from the latest successful build image. If the latest build failed (due to missing dependencies, syntax errors, or Dockerfile issues), users cannot run your actor at all and will see an error message. A broken build on a published actor means zero revenue until you fix it, plus potential maintenance flags if the downtime persists for more than 3 days. For this reason, always verify your build succeeded after pushing. To build an actor, use the Apify CLI: apify push. This command zips your source code (respecting .gitignore and .apify/.gitignore patterns), uploads it to Apify, and triggers the Docker build. Watch the build logs in real-time in the Apify Console under your actor's Builds tab, or via the CLI with apify builds ls. You can also trigger builds via the API: POST /v2/acts/{actorId}/builds with the version tag (e.g., 'latest'). The API returns a build object with an id you can poll for completion. The Dockerfile is central to the build process. Most Apify actors use the official base images: FROM apify/actor-node:20 for Node.js actors (includes Chrome for Playwright/Puppeteer), FROM apify/actor-node:20-minimal for lightweight HTTP-only actors (no browser, smaller image), or FROM apify/actor-python:3.11 for Python actors. The Dockerfile should COPY your source files, RUN npm install (or pip install), and set the CMD to start your actor. A minimal Dockerfile: FROM apify/actor-node:20 COPY package*.json ./ RUN npm install --omit=dev COPY . ./ CMD npm start. Common build failures include npm install errors from missing or incorrect package.json entries — always run npm install locally and verify package-lock.json is committed. Using the wrong base image is another frequent issue: if your actor uses Playwright but you use the -minimal base image, the browser binaries will be missing and the actor will crash at runtime (not at build time, which makes debugging harder). Exceeding the 1 GB build size limit typically happens when node_modules includes large native dependencies or you accidentally include data files — use a .dockerignore file to exclude test data, documentation, and other non-essential files. You can configure automatic builds on Git push via the Apify Console's Git integration tab. Connect your GitHub or GitLab repository, select the branch to track, and every push to that branch triggers a new build automatically. This enables CI/CD workflows where merging a pull request automatically deploys the latest code. For version management, use semantic versioning tags (0.1.0, 0.2.0, 1.0.0) and set the 'latest' tag to point to your most recent stable build. Build logs are retained for debugging and are accessible via the Console and API. If a build fails, read the logs carefully — they usually indicate the exact line in the Dockerfile or npm install output where the failure occurred. After fixing the issue, push again with apify push. Related concepts: Actor Run, Actor, Maintenance Flag, Dockerfile, Input Schema.