Skip to main content

Python API to interact with

Project description



Table of Contents


BeamNGpy is an official library providing a Python API to, the academia- and industry-oriented fork of the video game BeamNGpy and are designed to go hand in hand, both being kept up to date to support each other's functions, meaning using the latest versions of both is recommended.

It allows remote control of the simulation, including vehicles contained in it:


BeamNGpy comes with a wide range of low-level functions to interact with the simulation and a few higher-level interfaces that make more complex actions easier. Some features to highlight are:

Remote Control of Vehicles

Each vehicle can be controlled individually and independently during the simulation. This includes basic steering inputs, but also controls over various lights (headlights, indicators, etc.) or gear shifting.

Throttle control Steering control

AI-controlled Vehicles

Besides manual control, ships with its own AI to control vehicles. This AI can be configured and controlled from BeamNGpy. It can be used to make a vehicle drive to a certain waypoint, make it follow another vehicle, span the map, or follow a user-defined trajectory:

AI Trajectory

Dynamic Sensor Models

Vehicles and the environment can be equipped with various sensors that provide simulated sensor data. These sensors include:

  • Cameras
  • Color camera
  • Depth camera
  • Semantic and Instance annotations
  • Lidars
  • Inertial Measurement Units
  • Ultrasonic Distance Measurements

Multiple cameras Lidar

These sensors give perfect data from the simulation by default. Therefore, some of them, like the camera and lidar sensor, can be equipped to also simulate noisy data.

Access to Road Network & Scenario Objects

Geometry of roads in the currently-loaded level/scenario are made available via BeamNGpy. Objects and vehicles that are currently active in the scene are also exposed, allowing for analysis of the current simulation state.

Road Network

Multiple Clients

BeamNGpy interacts with as the client, with acting as the server. This allows for multiple BeamNGpy processes to connect to a running simulation and have each control the simulator, making it possible to, for example, run a scenario in which each vehicle is controlled by a separate client.


There is a healthy collection of usage examples in the examples/ folder of this repository. These highlight more features, but also serve as documentation, so be sure to check them out.


Usage of BeamNGpy requires to be installed. Builds of are made available for non-commercial use upon request using this form. For commercial use, contact us at Once downloaded (and extracted, depending on whether or no was obtained as a .zip), you can set an environment variable BNG_HOME to where can be run from, or provide a path to the BeamNGpy library during initialization.

The regular Steam release of is compatible to an extent as well. Certain sensors like the simulated LiDAR or camera will not work, but most of the functions that are not exclusive to a Tech build will likely work.


The library itself is available on PyPI and can therefore be installed using common methods like pip:

pip install beamngpy


For using version 0.22 and above the workspace needs to be set up by the user. This step needs to be repeated for every newly installed version and helps BeamNGpy to determine the correct user directory for mod deployment. Create a workspace directory and then place your license file into it. Then type beamngpy setup-workspace d:\exampleBNGworkspace into the commandline. Optional parameters are --host localhost --port 65255. Note that this functionality is only available for BeamNGpy version 1.19.2 and above.

Once set up, the library can be imported using import beamngpy. A short usage example setting up a scenario with one vehicle in the West Coast USA map that spans the area is:

from beamngpy import BeamNGpy, Scenario, Vehicle

# Instantiate BeamNGpy instance running the simulator from the given path,
# communicating over localhost:64256
bng = BeamNGpy('localhost', 64256, home='/path/to/bng/tech')
# Launch
# Create a scenario in west_coast_usa called 'example'
scenario = Scenario('west_coast_usa', 'example')
# Create an ETK800 with the licence plate 'PYTHON'
vehicle = Vehicle('ego_vehicle', model='etk800', licence='PYTHON')
# Add it to our scenario at this position and rotation
scenario.add_vehicle(vehicle, pos=(-717, 101, 118), rot=None, rot_quat=(0, 0, 0.3826834, 0.9238795))
# Place files defining our scenario for the simulator to read

# Load and start our scenario
# Make the vehicle's AI span the map
input('Hit enter when done...')

We have a guide helping you getting started and navigating our collection of examples and the documentation of the library is available here.

Compatibility is not a finished product but is still under development. Thus frequent changes on the simulation side are to be expected. While the BeamNGpy library maintains compatibility between minor versions for the user, this doesn't extend to the side. Not all BeamNGpy versions are compatible with all versions. Below is a list of compatible and BeamNGpy versions. However we do not maintain minor versions: bug fixes and new featrures will only be available for the newest and BeamNGpy releases. version BeamNGpy version
0.23 1.21
0.22 1.20
0.21 1.19


This section lists common issues with BeamNGpy in particular. Since this library is closely tied to and thus, it is also recommended to consult the documentation on here:

BeamNGpy cannot establish a connection

  • Be sure to complete the initial set up step described in the Usage section and to repeat it with every newly released version.
  • Make sure and Python are allowed to connect to your current network in Windows Firewall. quietly fails to launch

  • There is a known issue where quietly crashes when there is a space in the configured userpath. Until this issue is fixed, it is recommended to either switch to a path that does not contain a space or change the userpath directly in the "startup.ini" file located in the directory of your installation.


We always welcome user contributions, be sure to check out our contribution guidelines first, before starting your work.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for beamngpy, version 1.21
Filename, size File type Python version Upload date Hashes
Filename, size beamngpy-1.21-py2.py3-none-any.whl (81.5 kB) File type Wheel Python version py2.py3 Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page