Install & Compatibility
Where this runs
tested against v0.8.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.636s · 221MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 11.4s · import 1.409s · 825MB
522MB installed
● package 522MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
This example simulates one million particles under gravitational attraction using a Warp kernel. It demonstrates kernel definition, array allocation on a specific device, and launching a kernel. Note that for GPU execution, a compatible NVIDIA GPU and driver are required, and arrays must be explicitly placed on a 'cuda' device.
import warp as wp
import numpy as np
# Initialize Warp (optional, but good practice)
wp.init()
num_particles = 1_000_000
dt = 0.01
@wp.kernel
def gravity_step(pos: wp.array[wp.vec3], vel: wp.array[wp.vec3]):
i = wp.tid()
position = pos[i]
dist_sq = wp.length_sq(position) + 0.01 # softened distance
acc = -1000.0 / dist_sq * wp.normalize(position) # gravitational pull toward origin
vel[i] = vel[i] + acc * dt
pos[i] = pos[i] + vel[i] * dt
rng = np.random.default_rng(42)
positions = wp.array(rng.normal(size=(num_particles, 3)), dtype=wp.vec3, device='cuda')
velocities = wp.array(rng.normal(size=(num_particles, 3)), dtype=wp.vec3, device='cuda')
for _ in range(100):
wp.launch(kernel=gravity_step, dim=num_particles, inputs=[positions, velocities], device='cuda')
print(f"Final position of first particle: {positions.numpy()[0]}")
Debug
Known issues
breakingStarting from Warp v1.12.0, built-in functions and vector/matrix indexing for non-native scalar types (e.g., `wp.float16`, `wp.float64`) now return Warp scalar types instead of Python native types. Native types like `wp.int32` still return Python `int`. This change optimizes performance by avoiding implicit Python object creation.fixAccess 64-bit scalar results as Warp types (e.g., `result.value`) or set `wp.config.legacy_scalar_return_types = True` to restore previous behavior.
affects: >=1.12.0
deprecatedPython 3.9 support will be removed in Warp 1.13.0, making Python 3.10 the minimum supported version. A `DeprecationWarning` is currently emitted when using Python 3.9. Also, implicit conversion of scalar values to composite types (vectors, matrices) in kernel launches or struct field assignments is deprecated; explicit constructors (e.g., `wp.vec3(...)`) should be used.fixUpgrade to Python 3.10 or newer before Warp 1.13.0. Explicitly construct composite types: `wp.vec3(x, y, z)` instead of just `(x, y, z)`.
affects: >=1.12.0 (for Python 3.9 deprecation warnings), >=1.11.0 (for implicit conversion deprecation)
gotchaGPU acceleration requires an NVIDIA GPU and a CUDA driver. If the installed driver is too old (e.g., < 525 for CUDA 12.x wheels), Warp will issue a `UserWarning` and fall back to CPU-only execution, significantly impacting performance. macOS platforms only support CPU execution; GPU acceleration is not available.fixEnsure you have a compatible NVIDIA GPU and an up-to-date CUDA driver matching Warp's requirements. On macOS, be aware that only CPU execution is possible.
affects: All versions
gotchaWarp kernels (`@wp.kernel`) operate on a restricted subset of Python. All function arguments for kernels and `wp.func` functions must be explicitly typed, and kernels cannot return values. Control flow is limited, and arbitrary Python functions cannot be called inside kernels.fixDefine kernel arguments with type hints (e.g., `pos: wp.array[wp.vec3]`). Use Warp's built-in functions and structures within kernels. If complex logic is needed, consider offloading to helper `wp.func` functions (which also have typing and subset restrictions) or prepare data outside the kernel.
affects: All versions
gotchaAll Warp arrays used in a kernel launch must reside on the same device as specified for the kernel launch. Attempting to launch a kernel on a 'cpu' device with arrays allocated on 'cuda:0' (or vice-versa) will result in an error.fixEnsure `device` arguments for `wp.array` allocation and `wp.launch` are consistent. You can query the default device using `wp.get_device()`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'warp'
The `warp-lang` package, which is imported as `warp`, is not installed in the current Python environment.
AttributeError: 'list' object has no attribute 'ptr'
A standard Python list (or similar native Python object) was passed to a Warp function or kernel argument that expects a `wp.array` for GPU-managed memory.
fiximport warp as wp
my_python_list = [1.0, 2.0, 3.0]
my_wp_array = wp.array(my_python_list, dtype=wp.float32)
# Pass my_wp_array to the Warp function
TypeError: expected type 'wp.array(dtype=wp.float32)', got 'numpy.ndarray'
A NumPy array was passed to a Warp function or kernel argument that explicitly expects a `wp.array`, as Warp does not implicitly convert NumPy arrays for device operations.
fiximport warp as wp
import numpy as np
my_numpy_array = np.array([1.0, 2.0, 3.0], dtype=np.float32)
my_wp_array = wp.array(my_numpy_array, dtype=wp.float32)
# Pass my_wp_array to the Warp function
wp.errors.KernelCompilationError: NVRTC_ERROR_COMPILATION
There is a syntax error, type mismatch, unsupported operation, or invalid GPU code within a `wp.kernel` function, preventing successful compilation by the NVRTC compiler.
fixCarefully inspect the `wp.kernel` function for type mismatches, invalid operations, unsupported Python features, or incorrect Warp API usage, ensuring all types are explicit and consistent.
RuntimeError: CUDA error: out of memory
The GPU ran out of available memory, often due to allocating too many large `wp.array` objects or running computationally intensive kernels with large data sets.
fixReduce the size of `wp.array` allocations, free up unused GPU memory (e.g., by deleting arrays no longer needed), or run on a GPU with more VRAM.
Upgrade
Version history
1.16.0latest on PyPI · released Aug 3, 2026
Audit
Dependencies
numpyrequiredRequired for array handling and data initialization.
usd-coreoptionalOptional dependency for running examples and features related to Universal Scene Description (USD). On Linux aarch64, usd-exchange is used instead.
CUDA Toolkit and DriverrequiredRequired for GPU acceleration on NVIDIA GPUs (Windows/Linux). Minimum driver version varies by CUDA Toolkit version (e.g., ≥ 525 for CUDA 12.x, ≥ 580 for CUDA 13.x).