Skip to content

Tracking with Python

In this tutorial, you'll learn the three main ways to use CodeCarbon in your Python code. You can use CodeCarbon with any computing framework, and it supports both online (with internet access) and offline (without internet access) modes.

By the end of this tutorial, you'll understand which usage pattern works best for your use case.

Online Mode

When the environment has internet access, CodeCarbon will send your emissions data to the central API (optional). Let's start with three usage patterns: explicit object, context manager, and decorator.

Explicit Object

The explicit object pattern is useful when your code doesn't have a single entry and exit point—for example, in Jupyter notebooks where you want to start tracking in one cell and stop in a much later cell.

from codecarbon import EmissionsTracker
tracker = EmissionsTracker()
tracker.start()
try:
     # Compute intensive code goes here
     _ = 1 + 1
finally:
     tracker.stop()

Call tracker.start() at the beginning of your Notebook (or script), and call tracker.stop() at the end. You can also call tracker.flush() to write emissions to disk or the API without stopping the tracker entirely.

Advanced: Task-Level Monitoring

For fine-grained tracking of individual tasks within a single run, use the task manager:

try:
    tracker = EmissionsTracker(project_name="bert_inference", measure_power_secs=10)
    tracker.start_task("load dataset")
    dataset = load_dataset("imdb", split="test")
    imdb_emissions = tracker.stop_task()
    tracker.start_task("build model")
    model = build_model()
    model_emissions = tracker.stop_task()
finally:
    _ = tracker.stop()

The task manager tracks each sub-task independently. Tasks are not written to disk by default (to reduce overhead), so retrieve results from the stop_task() return value.

Context Manager

Now that you've seen the explicit object approach, let's look at the more idiomatic context manager pattern. This is the recommended way for most use cases.

from codecarbon import EmissionsTracker

with EmissionsTracker() as tracker:
    # Compute intensive training code goes here

This pattern is recommended when you want to monitor a specific block of code. The context manager automatically calls start() on entry and stop() on exit, making it safe and concise.

Decorator

Finally, if your training code is wrapped in a function, you can use the @track_emissions decorator for the simplest syntax.

from codecarbon import track_emissions

@track_emissions
def training_loop():
    # Compute intensive training code goes here

The decorator automatically wraps your function with tracking and writes results to emissions.csv. Use this when your code is neatly encapsulated in a function.

Note

All patterns create an emissions.csv file in your current directory containing detailed tracking data.

Offline Mode

So far we've assumed an internet connection. CodeCarbon also works fully offline without internet access. The internal computations remain unchanged; however, you must provide a country_iso_code parameter (3-letter ISO code) so CodeCarbon can estimate the carbon intensity of your regional electricity grid. See Wikipedia for a complete list of country codes.

The three usage patterns (explicit object, context manager, decorator) work the same in offline mode:

Explicit Object

Developers can use the OfflineEmissionsTracker object to track emissions as follows:

from codecarbon import OfflineEmissionsTracker
tracker = OfflineEmissionsTracker(country_iso_code="CAN")
tracker.start()
# GPU intensive training code
tracker.stop()

Context Manager

The OfflineEmissionsTracker also works as a context manager:

from codecarbon import OfflineEmissionsTracker

with OfflineEmissionsTracker(country_iso_code="CAN") as tracker:
    # GPU intensive training code goes here

Decorator

The decorator in offline mode requires two additional parameters:

from codecarbon import track_emissions

@track_emissions(offline=True, country_iso_code="CAN")
def training_loop():
    # training code goes here
    pass

What's Next?

You've now learned the three main patterns for tracking emissions in Python. Each pattern serves different use cases:

  • Use the explicit object pattern when your code runs across multiple cells or functions with unclear start/end points (e.g., Jupyter notebooks).
  • Use the context manager pattern for most new code—it's concise, safe, and idiomatic.
  • Use the decorator pattern when your entire tracking scope is a single function.
  • Use offline mode when you're in an environment without internet access.

Explore these related guides: