Depth Anything 3 usage: from pip install to your first depth map

You can watch the demand in Google's suggest box. Type depth anything api and the box finishes your query with the import line, from depth_anything_3.api import DepthAnything3. People paste Python into search because the quickstart lives in a repository, not on a product page. This page is that walkthrough, checked 28 October 2026 against the repository, its API document, and the model cards. It covers the pip route and the clone route, the import that works and the one that fails, the first call, the arrays that come back, the colormap flip, and the errors first calls hit.

Last verified: 2026-10-28

The one line that has to be right

The import is a single line, and the suffix decides whether it runs.

from depth_anything_3.api import DepthAnything3

That .api suffix is load bearing. The repository's own API document prints a shorter form once, from depth_anything_3 import DepthAnything3. We read the package source listing on 28 October 2026. There is no __init__.py at the top of the package, so the shorter line has nothing to bind the class name to. Python raises an ImportError on it. Every working example in the repository readme, in the API document's usage section, and on the model cards uses the .api path. Use it and move on.

The class you get has two constructors. DepthAnything3.from_pretrained("depth-anything/da3-small") loads weights from the model card by its Hugging Face id. DepthAnything3(model_name="da3-small") builds from a local preset name instead. Mind the default. Built the second way with no name, the class picks da3-large, the 0.35B tier. Name the tier you want, always.

Depth Anything 3 is the 2025 release from the ByteDance Seed team. It takes any number of views, with or without known camera poses, and returns depth plus camera geometry in one pass. The family story, the version comparison with V2, and the license split live on the comparison page. This page stays on the code.

Install: the pip route and the clone route

There are two ways to get the package, and both are real. The state of each, read 28 October 2026.

The pip route. The package is on PyPI.

pip install depth-anything-3

The PyPI page lists version 0.1.1. Both of its releases, 0.1.0 and 0.1.1, were uploaded 4 March 2026. The page declares Python 3.9 through 3.13, and its homepage field points at the official repository. Two honest caveats travel with it. The author field still reads "Your Name", so the packaging has not had a polish pass. And the repository readme still teaches the clone route as the primary install, so the wheel can trail the code between releases. For trying the model, the wheel is the fastest start.

The clone route. Clone the repository, then run the readme's install block.

git clone https://github.com/ByteDance-Seed/Depth-Anything-3
cd Depth-Anything-3
pip install xformers "torch>=2" torchvision
pip install -e .

The editable install runs against your checkout, so it always matches the code on disk. The project file pins the ecosystem around it: torch 2 or newer, xformers, numpy under 2, and moviepy at 1.0.3 exactly. Two extras exist. The app extra adds the Gradio interface and needs Python 3.10 or newer. The gs extra pulls a pinned gsplat commit for the gaussian splatting head. One naming note from the model table: refreshed 1.1 checkpoints exist for the large and giant tiers only, so the small tier has none.

The catch, either way: xformers. It is a hard dependency, and older cards have no matching binary. Issue 11 in the repository, now closed, works the case: a GTX 1060 on torch 2.4.1, no xformers build available, fixed with a small monkey patch in user code. If the install fights your CUDA setup, that thread is the map. And note the card's own example picks the device for you, cuda when present, cpu otherwise, so the package does run without a GPU. The CPU speed story, with measured numbers, is its own page: Depth Anything 3 small on a CPU.

The first call, line by line

Here is a complete first run on the small tier, the one this platform serves.

import torch
from depth_anything_3.api import DepthAnything3

device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
model = DepthAnything3.from_pretrained("depth-anything/da3-small")
model = model.to(device=device)

prediction = model.inference(["frame.jpg"])

Four things happen in those lines. The from_pretrained call pulls the weights from the model card on first run and caches them, so later runs start fast. Lowercase depth-anything/da3-small is the form the card's own example uses. The .to(device=device) call moves the model, and the device line itself is the card's line, not ours. And inference takes a list, always. One image is a list with one path in it. The list also takes PIL image objects and numpy arrays, so a loop that holds frames in memory never needs to write them to disk first.

The model behind the id is da3-small on this platform, 0.08B parameters under Apache 2.0 per the repository's model table. It is the tier built for cheap, quick depth. The first call returns a Prediction object, and reading it right is the next job.

What comes back: the Prediction object

One call fills six fields. The shapes below are the repository's own annotations.

N is the number of images you passed. H and W are the processed resolution, not always your input resolution, because the model resizes to process_res first. A 1200 by 1600 photo becomes 378 by 504 under the default resize rule. If you compare pixel values against your original frame, index from processed_images, not from your file.

Two of these fields need a warning label. The depth values are relative, scale and shift invariant. They order the scene from near to far. They are not meters. The repository FAQ gives the one formula that produces meters, and only for a different tier. Per that FAQ, the metric model returns meters via focal * net_output / 300, with focal in pixels. The any-view tiers, small included, do not. If your robot needs true distance, plan a scale calibration on your side, or read the metric tier's card first.

The second warning is the colormap flip, and it deserves its own section.

The depth convention that inverts colormaps

Depth Anything 2 predicted inverse depth. Larger values meant closer surfaces. Depth Anything 3 predicts depth. Larger values mean farther surfaces. If you migrate V2 rendering code, near and far swap, and the depth maps look wrong in a way that reads like model failure.

This is documented, not folklore. The readme says the same about the family's monocular tier: it directly predicts depth, where disparity-based models like V2 do not. Issue 71 on the repository, opened about DA3-SMALL, compared the two small tiers and saw inverted output. The reporter's own post on that thread states it plainly: "The colormaps are inverted between DA3 and DAv2 since they are trained to predict scale-and-shift-invariant depth and inverse depth, respectively." The fix in your code is one division. A commenter on the same thread renders DA3 with 1.0 / depth to recover the look V2 tools expect. The fuller migration story, including what else changed between the versions, is on the DA3 versus V2 page.

The inference parameters that matter

Most first calls need none of these. They all carry defaults, and the defaults are sane. The table is the full parameter surface from the API document, read 28 October 2026.

Three of these earn the most attention in practice. The resolution pair, process_res with process_res_method, is the quality and memory lever. The issue 71 thread already quoted above has a user raising resolution for quality and flagging the memory cost in the same breath. Set it once, measure, and leave it. The reference view strategy matters once you feed video or ordered capture, where middle fits temporally ordered frames better than the balanced default. And use_ray_pose is the accuracy knob: the readme calls the ray head slightly slower but more accurate, and leaves it off by default for speed.

Export is one argument, not a second pipeline. Pass export_dir and export_format to inference and the files land on disk. mini_npz holds the raw arrays. npz holds the full set. glb gives a viewable mesh with cameras. depth_vis writes color coded maps, feat_vis writes feature videos, and gs_ply with gs_video carry gaussian splatting. The last two need infer_gs=True, and that branch exists only on the giant tiers. On the small tier those formats are not yours to call.

Multi-view and pose conditioning, briefly

The reason DA3 exists is in two optional arguments. Send several views of one scene in the image list, and the model estimates the camera poses between them, which is why extrinsics comes back full. Supply your own extrinsics and intrinsics arrays instead, and the model conditions depth on your known poses, which tightens consistency across frames. The align_to_input_ext_scale flag then decides the scale of what comes back. With it True, the default, depth is rescaled to the metric scale of the poses you supplied.

The shape laws come from the API document. Extrinsics goes in as N by 4 by 4 and comes out as N by 3 by 4, world to camera. That output uses the OpenCV convention, the one COLMAP uses. Intrinsics is N by 3 by 3 both ways. Feed the arrays as numpy, one entry per image, in the same order as the image list.

The CLI, for runs without Python

The package installs a command line tool named da3. Its command reference lists eight commands: auto, image, images, video, colmap, backend, gradio, and gallery. The one worth knowing first is backend, which keeps the model resident in GPU memory so later jobs skip the load.

da3 backend --model-dir depth-anything/da3-small
da3 auto path/to/input --export-dir workspace/gallery/scene001 --use-backend

The backend listens on localhost port 8008 by default, and jobs reach it through the --use-backend flag. One quirk from the CLI document: with --use-backend, the export directory must sit under the backend's gallery directory, workspace/gallery by default. The backend process writes the files, not your shell. Local runs without the flag can write anywhere. The gradio command needs the app extra installed and Python 3.10 or newer. Each export directory comes out with scene.glb and scene.jpg in it, plus extras you asked for.

Six errors the first call hits

Every item below is a real, dated thread in the repository, or a documented default. They are ordered by how often they bite.

The bare import fails

Symptom: ImportError, cannot import name. Cause: the line without .api, covered at the top of this page. The API document prints the bare form once in its class section, so the mistake is easy to make from the official docs. Fix: from depth_anything_3.api import DepthAnything3.

The transformers loader does not know the model

Symptom: an attempt to load DA3 through the transformers library fails. State: expected. The models are not in transformers. Issue 182, open as of 28 October 2026, is the feature request to add pipeline support, and it describes the current answer itself: the models load through the depth_anything_3 package. Do not fight the loader. Use the class on this page.

The depth map looks inverted

Symptom: near surfaces render far, far surfaces render near, most often in code carried over from V2. Cause: the depth versus inverse depth convention, quoted from the issue reporter above. Fix: one division by 1.0 / depth in your rendering path, or a colormap that expects depth instead of disparity.

No xformers binary for your card

Symptom: the install or the first forward pass fails on xformers, most often on older GPUs. Cause: xformers ships binaries only for newer architectures. Fix: issue 11, closed, carries a monkey patch tested on a GTX 1060 with torch 2.4.1. The clone route plus that patch is the documented escape.

Gaussian exports fail on the small tier

Symptom: gs_ply or gs_video export errors, or infer_gs=True refuses. Cause: the gaussian branch is built for da3-giant and da3nested-giant-large only, stated in the API document's own note on the gs example. Fix: none on the small tier. Switch tiers, or take your glb export and move on.

Batching looks worse than one at a time

Symptom: ten images in one call give softer maps than the same ten run singly. This is issue 68, open, reported exactly that way on the hosted demo. There is no fix yet, only the workaround: benchmark your workload both ways before you standardize on batched calls. For the out of memory family on video runs, a sibling page collects the cases: Depth Anything video OOM errors.

Skip the install: the same model over HTTP

Everything above runs on your machine. There is also a served copy of the small tier. This platform's da3-small lane has served since 6 October 2026, metered per image, and it takes the install problem off your desk entirely. The route is one multipart POST.

Open an account on the console, create a key, and set two variables. Every key step is walked in the quickstart.

export IRONSTRATUM_BASE_URL="https://api.example.invalid"
export IRONSTRATUM_API_KEY="sk-ironstratum-your-key"

One line of curl makes the first call.

curl -sS $IRONSTRATUM_BASE_URL/v1/vision \
  -H "Authorization: Bearer $IRONSTRATUM_API_KEY" \
  -F "model=da3-small" \
  -F "file=@frame.jpg"

Two fields come back in the JSON. annotations is an array carrying the model's own output objects for each image you sent. Its partner, usage, carries the billed image count and the wallet debit. Field by field, the contract, the error table, and the count law live on the vision route page. A run-vision reference page holds the machine shape.

{
  "annotations": ["the model's own depth objects, one per image"],
  "usage": { "images": 1, "cost": "the wallet debit, six decimals" }
}

Billing counts the image, and you can predict it from what you send: three file parts bill three images. Across the whole multipart request, the body cap is 25 MiB, and a network retry bills again, because image bodies are not replayed. Rates for the lane render from the platform's model data.

Budget math continues in the next page of this set: Depth Anything 3 small API pricing. It also carries the census of who else sells this family, and at what unit. Live rates for every listed row are on the pricing page.

Which surface, when

Two honest picks, and the job decides.

Self-host when you need the deep surface. That means pose conditioning on your own calibration, the export formats, the giant tiers, or full control of the resolution and memory trade. You own the GPU, the install from this page, and the uptime. The local hardware economics, from measured runs, are worked on the CPU tier page.

Use the lane when depth is a step in a pipeline, not the product. One image in, one depth map out. No serving work, and a fixed contract you can test against today. The client is the curl line above. The bill is the image count. A mixed setup is also normal: local for development, the lane for bursts. The model id and the output convention are the same on both sides.

Frequently asked questions

What is the import line for Depth Anything 3?

from depth_anything_3.api import DepthAnything3. The .api suffix is required. The package has no top level re-export, so the bare form, from depth_anything_3 import DepthAnything3, raises an ImportError. Suggest data shows people search the bare form, which is why this answer sits first. Checked 28 October 2026 against the package source listing.

Is pip install depth-anything-3 official?

Yes, in the sense that matters: the PyPI page's homepage field points at the official repository, and the package name is the project's own. Version 0.1.1 went up 4 March 2026. It declares Python 3.9 through 3.13. The readme still teaches clone plus editable install as the primary route, so treat the wheel as the fast start and the clone as the freshest code. Both give you the same class and the same CLI.

Can I load DA3 with transformers?

No. The models are not in the transformers library. Issue 182 is the open feature request for pipeline support, still open as of 28 October 2026. Until it lands, the loading path is the package's own class, DepthAnything3.from_pretrained, from this page.

Why is my depth map inverted compared to V2?

Convention, not a bug. V2 predicted inverse depth, where larger means closer. DA3 predicts depth, where larger means farther. The issue 71 reporter states it plainly: the colormaps are inverted because the two models predict depth and inverse depth respectively. Divide by one over depth, 1.0 / depth, in render code carried over from V2.

Does DA3 small return metric depth in meters?

No. The any-view tiers, small included, return relative depth, scale and shift invariant. The repository FAQ gives the meters formula for the metric tier only: focal * net_output / 300, with focal in pixels, and notes the nested giant model outputs meters natively. For true distances from the small tier, calibrate scale against a known object in your scene.

Is there a hosted API for DA3 without self-hosting?

Yes. This platform serves the small tier over its vision route, per image, since 6 October 2026. The request is one multipart POST with the model id and your image files. Your key comes from the console, and the live rate is on the pricing page. The seller census for the whole family, every unit dated, is on the pricing guide.

Sources

• Depth Anything 3 repository: readme install block, basic usage, model table, use_ray_pose note, metric depth FAQ. Read 28 October 2026.
• API document: constructors, parameter defaults, export formats, return shapes. Read 28 October 2026.
• CLI document: the eight commands, backend defaults, gallery directory rule. Read 28 October 2026.
• DA3-SMALL model card: the card example code and the device line. Read 28 October 2026.
• pyproject.toml: dependencies, extras, the da3 script entry. Read 28 October 2026.
• PyPI page for depth-anything-3: version, upload dates, Python range, homepage. Read 28 October 2026.
• Issue 71, issue 182, issue 11, issue 68. Read 28 October 2026.
• Depth Anything 3 paper, the 2025 release reference.

The short version: import from .api, and install from pip or clone. Send a list to inference. Read relative depth with near small and far large. Mind the six first-call errors, each one linked to its dated thread. When you would rather not host at all, the small tier serves per image on the vision route, and the first call is one curl line. The console opens the account, the pricing page carries the live rate, and the quickstart holds the key setup.

Last verified: 2026-10-28