# Kubric: a synthetic video generator built on pybullet and Blender > Kubric generates multi-object videos with instance segmentation masks, depth maps and optical flow, using pybullet for physics and Blender 2.93 for rendering. It is research infrastructure with a Docker-first install and a 2021 PyPI release. **google-research/kubric** — A data generation pipeline for creating semi-realistic synthetic multi-object videos with rich annotations such as instance segmentation masks, depth maps, and optical flow. - Repository: https://github.com/google-research/kubric - Stars: 2,826 · Forks: 278 - Language: Jupyter Notebook - License: Apache-2.0 - Published: 2026-09-28 · Updated: 2026-09-28 · Language: en - Canonical page: https://hysenlabs.com/projects/google-research-kubric ## What Kubric generates, and who the annotations are for Kubric is a data generation pipeline for creating semi-realistic synthetic multi-object videos with rich annotations: instance segmentation masks, depth maps and optical flow. The README frames the motivation around unsupervised multi-object video understanding, arguing that current systems succeed on toy datasets but fail on real-world data, and that progress would be accelerated by the ability to create suitable datasets of varying complexity on demand. That sentence defines the audience narrowly. Kubric is for researchers who need ground truth that real video cannot provide: per-object masks, depth and flow that are exact by construction rather than estimated. The README's requirements list is explicit about what the pipeline must offer, including physics simulation for automatically generating physical interactions between multiple objects, control over complexity so individual aspects such as variability of objects and textures can be evaluated, and control of the train/test split to evaluate compositionality and systematic generalization on held-out combinations of features or objects. If your problem is 'I have 500 hours of video and no labels', Kubric does not help. It does not annotate your footage. It produces new footage alongside its own labels, and the domain gap between rendered scenes and your camera is yours to manage. ## pybullet for physics, Blender 2.93 for rendering, and a modular seam between them The architecture is two engines in sequence. pybullet runs the physics simulation, producing object trajectories and interactions. Blender renders those trajectories into images. The README states that Kubric is mainly built on top of pybullet and Blender, and that the code is kept modular to potentially support different rendering backends. The modularity claim is worth reading carefully. 'Potentially support' is not the same as a documented plugin interface, and the README does not describe how a third rendering backend would be registered. Treat the Blender backend as the one that exists. The version pin matters more than it first appears. The README states that Kubric employs Blender 2.93, and that if you want to inspect the generated .blend scene file for interactive inspection without rendering, you should make sure you have installed the correct Blender version. Blender's .blend format is not forward compatible in practice. If you open a Kubric scene in a newer Blender and save it, you should expect the file to stop loading in the pinned version. The docker/Blender.Dockerfile in the repository is where that version is fixed, and the Makefile builds it as kubricdockerhub/blender:latest. ## Installing Kubric with Docker and running the helloworld example The README does not give a pip install path for the full pipeline, and requirements.txt explains why: the bpy line is commented out with the note that it is the Blender python module and cannot be pip-installed. The documented route is Docker. The README says that assuming you have docker installed, you generate the example data by cloning the repository, pulling the kubruntu image, and running helloworld.py inside it with your working directory mounted at /kubric. ```bash git clone https://github.com/google-research/kubric.git cd kubric docker pull kubricdockerhub/kubruntu docker run --rm --interactive \ --user $(id -u):$(id -g) \ --volume "$(pwd):/kubric" \ kubricdockerhub/kubruntu \ /usr/bin/python3 examples/helloworld.py ls output ``` The --user flag passes your host uid and gid into the container, and the --volume flag mounts the clone at /kubric, so the run writes into the output directory of your own checkout rather than into the container filesystem. The final ls output is the check that matters: if the directory is empty, the run failed silently somewhere upstream. The README shows this exact sequence, including the ls, which suggests the authors expect output inspection to be part of the first run. The repository also ships a development image path. The Makefile defines kubruntudev and a kubruntudev/bash target that starts an interactive bash inside kubricdockerhub/kubruntudev with your working directory mounted at /workspace. That target depends on checkmakeversion, which fails with 'ERROR: make>=3.82 needed' if your make is older. Note the mount point differs between the two flows: /kubric for the helloworld command, /workspace for the dev shell. ## The release history is the real constraint The PyPI story is thin. There are two releases: v0.1, described as a pre-release deployed to pypi, and v0.1.1 with fixed TFDS requirements, both published on 2021-08-25. Nothing has been released since. The repository's setup.py supports --tag, --nightly and --secondly version modes, with a fallback that stamps the version from the current datetime down to the second, and the Makefile's dist target builds an sdist and wheel from setup.py. So the machinery for versioned releases exists; the published tags simply stop in 2021. The last push to main was on 2026-05-21, so the repository is not archived and has seen commits this year. That is not the same as a stable API surface. If you install from git or from the container rather than from a 2021 wheel, you are tracking main, and nothing in the README describes a compatibility policy for that. The practical consequence: pin the image tag or the commit you validated, and treat any later pull as a change to re-validate, because the README does not document rollback or a supported upgrade path between versions. ## Where Kubric is the wrong tool Realism is the first boundary, and the README concedes it. The stated requirement is the ability to span the entire complexity range from CLEVR all the way to real-world video such as YouTube8, followed immediately by 'This is clearly not feasible'. Kubric is positioned as getting as close as possible, not as closing the gap. If your evaluation depends on photorealism or on material and lighting behaviour that Blender 2.93 with the shipped assets does not reproduce, synthetic results will not transfer, and no amount of pipeline configuration fixes that. The second boundary is the install. Because bpy cannot be pip-installed, a plain pip install kubric does not give you a working renderer. If your environment cannot run Docker, or your cluster forbids the container runtime, the documented path is closed to you, and the README offers no alternative. The third boundary is scope. Kubric generates datasets; it does not train models, and it does not label existing video. It also does not ship the challenge datasets inside the repository. The README points to a Google Cloud Bucket named kubric-public where datasets for the challenges are stored, and lists the challenges as dataset contributions of the Kubric CVPR'22 paper, including MOVi, Optical Flow, Robust NeRF and Point Tracking. If you want MOVi rather than your own generated scenes, you are downloading from that bucket, not running the generator. ## Compared with writing scene generators directly against Blender The obvious alternative is building your own generator on Blender's Python API, or on a physics engine plus a renderer of your choice. The difference is what you inherit. A hand-rolled generator gives you exact control over the scene and no dependency on someone else's abstraction; you also own the annotation writer, the camera sampling, the physics stepping and the export format for every modality you need. Kubric's contribution is that those pieces already exist as a pipeline with a defined output, including segmentation masks, depth maps and optical flow, and with the Shapenet integration visible in examples/shapenet.py and the shapenet2kubric/ directory at the repository root. The examples directory shows the intended surface: helloworld.py, basic.py, bouncing_balls.py, animation.py, keyframing.py, simulator.py and shapenet.py. Reading those seven files is a faster way to judge the API than reading the README, which delegates setup to the ReadTheDocs site. The cost of that inheritance is the pinned Blender 2.93 and the container. You trade control over the renderer for a working annotation pipeline. That trade is reasonable for a lab that needs data next month and unreasonable for a team that needs to ship a renderer-dependent product. ## Licence, maintenance and the cost of upgrading Kubric is Apache-2.0, and the LICENSE file is at the repository root. Apache-2.0 is a permissive licence with an explicit patent grant and a requirement to preserve notices; the setup.py header carries the standard Apache boilerplate and a 2026 copyright line for The Kubric Authors. The README adds a disclaimer that this is not an official Google Product, which matters if your organisation's approval process treats Google-published repositories as supported products. They are not, here. This is a description of the licence text and the disclaimer, not legal advice. The upgrade cost follows from the release gap. With no tagged release since 2021-08-25, there is no changelog-driven upgrade path to follow. The container image is pulled as kubricdockerhub/kubruntu without a tag in the README's example, which resolves to latest; the Makefile shows that pushes to these images are done automatically by GitHub Actions on push to the main branch. A pull therefore can change the Blender version, the Python dependencies or both. If you need reproducibility across a paper or a product milestone, record the image digest you used, not the tag. ## Conclusion Adopt Kubric if you need controlled multi-object video data with ground-truth masks, depth and flow, and you can run Docker plus the kubricdockerhub/kubruntu image. Do not adopt it if you need a pip-only install, a stable tagged API, or a maintained release cadence: the last release was v0.1.1 on 2021-08-25 and the last push to main was on 2026-05-21. Verify three things before committing a project to it: that the helloworld example produces an output directory on your hardware, that Blender 2.93 is the version your inspection workflow needs because the README names that version specifically, and that Apache-2.0 plus the 'not an official Google Product' disclaimer fits your organisation's dependency policy. ## FAQ ### How do I install Kubric? The README documents a Docker route: clone the repository, pull kubricdockerhub/kubruntu, and run examples/helloworld.py inside the container with your checkout mounted at /kubric. A pip install of the full pipeline is not documented, because requirements.txt notes that bpy, the Blender python module, cannot be pip-installed. ### Can I download the Kubric dataset instead of generating it? Yes. The README states that datasets for the challenges are generally stored in a Google Cloud Bucket named kubric-public, and lists challenges such as MOVi, Optical Flow, Robust NeRF and Point Tracking as dataset contributions of the Kubric CVPR'22 paper. ### Which Blender version does Kubric use? The README states that Kubric employs Blender 2.93, and that you should install the correct Blender version if you want to inspect the generated .blend scene file interactively without rendering. ### What does the Kubric paper describe? The README cites it as 'Kubric: a scalable dataset generator', published in the Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition (CVPR), year 2022, with Klaus Greff as first author. ## Sources - [google-research/kubric on GitHub](https://github.com/google-research/kubric) - [Issues](https://github.com/google-research/kubric/issues) - [License: Apache-2.0](https://github.com/google-research/kubric/blob/main/LICENSE) - [README](https://github.com/google-research/kubric/blob/main/README.md) - [Releases](https://github.com/google-research/kubric/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/google-research-kubric