{"id":7811,"library":"tuna","title":"Tuna","description":"Tuna is a modern, lightweight Python profile viewer, currently at version 0.5.13. Inspired by SnakeViz, it visualizes Python runtime and import profiles, offering a faster and more accurate alternative by leveraging d3 and bootstrap for its web-based interface. The project maintains an active development status with regular minor updates.","status":"active","version":"0.5.13","language":"en","source_language":"en","source_url":"https://github.com/nschloe/tuna","tags":["profiling","performance","visualization","debugging","developer-tools"],"install":[{"cmd":"pip install tuna","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.10 or newer. Relies on built-in cProfile and -X importtime.","package":"python","optional":false}],"imports":[{"note":"Tuna is primarily a command-line tool or an IPython magic, not a library meant for direct Python imports for its core visualization functionality. It operates on profile files generated by cProfile or importtime.","wrong":"from tuna import visualize","symbol":"tuna CLI","correct":"tuna your_profile.prof"},{"note":"The IPython magic must be loaded first in a session before it can be used.","wrong":"%tuna your_code() (without loading extension)","symbol":"%tuna IPython magic","correct":"%load_ext tuna\n%tuna your_code()"}],"quickstart":{"code":"import cProfile\nimport time\n\ndef func_a():\n    time.sleep(0.1)\n\ndef func_b():\n    func_a()\n    time.sleep(0.05)\n\ndef main():\n    func_a()\n    func_b()\n\nprofile_file = 'my_program.prof'\ncProfile.run('main()', profile_file)\n\nprint(f\"Profile saved to {profile_file}. View with: tuna {profile_file}\")\n\n# To view import profile (run from terminal):\n# python -X importtime -c \"import pandas\" 2> import.log\n# print(\"Import profile saved to import.log. View with: tuna import.log\")","lang":"python","description":"Generate a runtime profile using Python's built-in `cProfile` module, saving the output to a file. Then, visualize the profile by running the `tuna` command-line tool with the generated profile file. Alternatively, you can profile import times by redirecting `python -X importtime` output to a log file and viewing it with `tuna`."},"warnings":[{"fix":"This is a design choice for accuracy. Understand that the displayed call tree reflects what's reliably measurable from `cProfile` output. If you need a full, but potentially less accurate, call tree, other profilers might be necessary, but Tuna prioritizes accurate timings within its scope.","message":"Tuna's visualization of the call tree is intentionally incomplete compared to some other profilers (e.g., older SnakeViz versions). It only displays the part of the timed call tree that can be directly deduced from the profile data, as Python's profilers (like cProfile) do not store the full contextual call hierarchy (e.g., differentiating calls to the same function from different parents).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always run `%load_ext tuna` at the beginning of your IPython session or notebook before attempting to use `%tuna` or `%%tuna` magics.","message":"When using `tuna` as an IPython magic (e.g., in Jupyter notebooks), you must explicitly load the extension first.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure your virtual environment is activated. If installed with `--user`, add `~/.local/bin` (or equivalent for your OS) to your system's PATH. On Linux/macOS, this typically involves adding `export PATH=\"$HOME/.local/bin:$PATH\"` to your shell's configuration file (e.g., `.bashrc`, `.zshrc`).","cause":"The `tuna` executable is not in your system's PATH. This often happens if `pip install tuna` was run with `--user` and the user's bin directory is not in PATH, or if the virtual environment is not activated.","error":"tuna: command not found"},{"fix":"Verify that the profile file (e.g., `program.prof` or `import.log`) exists at the specified path. Double-check the filename and its location. Ensure the profiling command (e.g., `python -mcProfile -o ...` or `python -X importtime ...`) executed successfully and created the output file.","cause":"The `tuna` command was run with a profile file name that does not exist in the current directory or the specified path is incorrect.","error":"Error: profile file 'program.prof' not found."},{"fix":"Debug your application code directly to identify the type mismatch. Tuna visualizes *how* your code performs, but it doesn't prevent or diagnose application-level runtime errors. Use standard Python debugging techniques.","cause":"This is a general Python error, but if encountered during profiling or within the profiled code, it's typically an issue within the application logic being profiled, not `tuna` itself.","error":"TypeError: unsupported operand type(s) for +: 'int' and 'str'"}]}