{"id":8022,"library":"codecarbon","title":"CodeCarbon","description":"CodeCarbon is an open-source Python library that helps estimate and track the CO2 emissions produced by computing, particularly for machine learning models. It measures energy consumption of CPU, GPU, and RAM, and combines it with regional carbon intensity data to provide CO2 equivalent emissions. Currently at version 3.2.6, it maintains an active development and release cadence, offering both Python API and CLI for monitoring and reporting.","status":"active","version":"3.2.6","language":"en","source_language":"en","source_url":"https://github.com/mlco2/codecarbon","tags":["machine learning","sustainability","carbon footprint","monitoring","eco-friendly","mlops","energy"],"install":[{"cmd":"pip install codecarbon","lang":"bash","label":"PyPI"},{"cmd":"conda install -c conda-forge codecarbon","lang":"bash","label":"Conda"}],"dependencies":[{"reason":"Minimum Python version required for the library.","package":"python","optional":false},{"reason":"Required for accurate NVIDIA GPU power consumption tracking. CodeCarbon falls back to estimation without it.","package":"pynvml","optional":true},{"reason":"Optional, but recommended for accurate Intel CPU power consumption tracking on supported systems (Linux/Windows). CodeCarbon falls back to estimation without it.","package":"intel-power-gadget","optional":true},{"reason":"Optional, but recommended for accurate Intel CPU power consumption tracking on supported systems (Linux). CodeCarbon falls back to estimation without it.","package":"intel-rapl","optional":true},{"reason":"Required for AMD ROCm support for GPU power tracking (introduced in v3.2.4).","package":"amdsmi","optional":true},{"reason":"CLI tool and dashboard for local visualization of CodeCarbon's `emissions.csv` output.","package":"carbonboard","optional":true}],"imports":[{"symbol":"EmissionsTracker","correct":"from codecarbon import EmissionsTracker"},{"note":"The `track_emissions` function is typically used as a decorator and is directly imported from the `codecarbon` package.","wrong":"import codecarbon; codecarbon.track_emissions","symbol":"track_emissions","correct":"from codecarbon import track_emissions"},{"symbol":"OfflineEmissionsTracker","correct":"from codecarbon import OfflineEmissionsTracker"}],"quickstart":{"code":"import time\nfrom codecarbon import EmissionsTracker\n\ndef train_model():\n    # Simulate some computationally intensive task\n    print(\"Starting model training...\")\n    time.sleep(10) # Your actual ML code here\n    print(\"Model training finished.\")\n\nif __name__ == \"__main__\":\n    tracker = EmissionsTracker()\n    tracker.start()\n    train_model()\n    emissions = tracker.stop()\n    print(f\"Emissions: {emissions} kg CO₂\")\n    print(\"Check emissions.csv for detailed report.\")","lang":"python","description":"This quickstart demonstrates how to use the `EmissionsTracker` class to measure the carbon footprint of a Python code block. It initializes a tracker, starts it before the task, stops it after, and prints the total emissions. A detailed report is saved to `emissions.csv` by default."},"warnings":[{"fix":"Ensure you are using `codecarbon==3.2.5` or later. If you installed 3.2.4, uninstall it and reinstall the latest version: `pip uninstall codecarbon && pip install codecarbon`.","message":"Version 3.2.4 was broken due to packaging issues and was subsequently yanked from PyPI. Direct upgrades to 3.2.4 might have failed or resulted in a broken installation.","severity":"breaking","affected_versions":"3.2.4"},{"fix":"Review the official CodeCarbon documentation for changes to API endpoints, authentication, and configuration files (`.codecarbon.config`). Re-run `codecarbon login` if using the online dashboard.","message":"CodeCarbon has updated its underlying APIs for carbon intensity data (e.g., from CO2 Signal to Electricity Maps) and its authentication backend (from Fief to Keycloak). Users relying on specific API integrations or the CodeCarbon dashboard might need to update configurations or API keys.","severity":"breaking","affected_versions":"3.1.1, 3.2.3"},{"fix":"For the most accurate tracking, consult the CodeCarbon documentation's methodology section to install the recommended power measurement tools for your specific hardware and OS.","message":"The accuracy of hardware power consumption measurements (CPU, GPU) depends on the availability of specific underlying tools (e.g., Intel Power Gadget/RAPL, pynvml, amdsmi) on your operating system. Without these, CodeCarbon will fall back to less accurate estimation methods.","severity":"gotcha","affected_versions":"All"},{"fix":"If you need to run multiple trackers, initialize `EmissionsTracker` with `allow_multiple_runs=True`. If an error occurs due to a stale lock file, manually delete `/tmp/.codecarbon.lock` (or equivalent on your OS) or restart your environment.","message":"By default, CodeCarbon's `EmissionsTracker` uses a lock file to prevent multiple instances from running concurrently in the same directory, which can cause an error if a previous run crashed or if you intentionally try to run multiple trackers.","severity":"gotcha","affected_versions":"All"},{"fix":"For tracking remote GenAI API call emissions, consider using complementary tools like EcoLogits. CodeCarbon is intended for monitoring code running on your local machine or managed compute infrastructure.","message":"CodeCarbon measures emissions from local computing (your hardware). It does not track emissions from remote GenAI API calls (e.g., OpenAI, Anthropic, Mistral). For those, CodeCarbon recommends using EcoLogits.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"If you intended to run multiple trackers, initialize with `EmissionsTracker(allow_multiple_runs=True)`. Otherwise, ensure no other `codecarbon` process is running or manually delete the lock file (e.g., `/tmp/.codecarbon.lock` on Linux).","cause":"An `EmissionsTracker` instance detected a lock file, indicating another tracker is active or a previous run terminated abnormally.","error":"Another instance of codecarbon is probably running as we find /tmp/.codecarbon.lock. Turn off the other instance to be able to run this one or use allow_multiple_runs or delete the file. Exiting."},{"fix":"Verify your internet connection. Check the `api_endpoint`, `api_key`, `organization_id`, `project_id`, and `experiment_id` in your global `~/.codecarbon.config` or local `.codecarbon.config` file. Re-run `codecarbon login` or `codecarbon config` CLI commands to re-authenticate and configure.","cause":"Failed communication with the CodeCarbon online API, often due to misconfigured API keys, project IDs, or network issues.","error":"ApiClient Error when calling the API on https://api.codecarbon.io/... API return http code 500 and answer : {\"detail\":\"Generic error\"}"},{"fix":"Ensure `codecarbon` is correctly installed: `pip install --upgrade codecarbon`. Verify the import statement: `from codecarbon import EmissionsTracker`. If running in an IDE, restart the Python kernel or environment.","cause":"The `EmissionsTracker` class was not found when attempting to import, likely due to a partial installation, a corrupted environment, or incorrect import statement.","error":"AttributeError: module 'codecarbon' has no attribute 'EmissionsTracker'"},{"fix":"Ensure `tracker.stop()` is called before trying to access `emissions.csv`. The file is saved in the directory where the script is run by default, or to a path specified by the `save_to_file` parameter in `EmissionsTracker`.","cause":"Attempting to read `emissions.csv` before `EmissionsTracker.stop()` has been called, or the file was saved to a different location.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'emissions.csv'"}]}