{"id":9630,"library":"csv2md","title":"CSV to Markdown Converter","description":"csv2md is a command-line tool for converting CSV files into formatted Markdown tables. As of version 1.5.0, it is actively maintained with minor releases addressing features and bug fixes roughly every few months, ensuring correct escaping and handling of various CSV structures.","status":"active","version":"1.5.0","language":"en","source_language":"en","source_url":"https://github.com/lzakharov/csv2md","tags":["csv","markdown","cli","converter","table"],"install":[{"cmd":"pip install csv2md","lang":"bash","label":"Install csv2md"}],"dependencies":[],"imports":[{"note":"The library is primarily a CLI tool. For programmatic use, import the 'convert' function, which expects a file-like object.","wrong":"import csv2md","symbol":"convert","correct":"from csv2md import convert"}],"quickstart":{"code":"import os\nimport subprocess\nimport tempfile\nimport io\n\n# 1. Create a dummy CSV file for demonstration\ncsv_content = \"\"\"Name,Age,City\nAlice,30,New York\nBob,24,London\nCharlie,22,\"San Francisco|CA\"\"\" # Includes a pipe for testing escaping\n\ncsv_file_path = None\ntry:\n    with tempfile.NamedTemporaryFile(mode='w', delete=False, suffix=\".csv\", encoding=\"utf-8\") as temp_csv_file:\n        csv_file_path = temp_csv_file.name\n        temp_csv_file.write(csv_content)\n        temp_csv_file.flush() # Ensure content is written to disk\n\n    print(f\"--- CLI Usage (requires csv2md installed): {csv_file_path} ---\")\n    # This will only work if csv2md is installed and in PATH\n    try:\n        # Check if csv2md command is available\n        subprocess.run([\"csv2md\", \"--version\"], capture_output=True, check=True)\n        cmd_output = subprocess.run(\n            [\"csv2md\", \"--\", csv_file_path], # Use -- to separate options from filename\n            capture_output=True, text=True, check=True, encoding=\"utf-8\"\n        )\n        print(cmd_output.stdout.strip())\n    except FileNotFoundError:\n        print(\"Skipping CLI example: 'csv2md' command not found. Please 'pip install csv2md'.\")\n    except subprocess.CalledProcessError as e:\n        print(f\"CLI Error: {e.stderr.strip()}\")\n        print(f\"Output: {e.stdout.strip()}\")\n\n\n    print(\"\\n--- Programmatic Usage (importing convert function) ---\")\n    try:\n        from csv2md import convert\n        # The 'convert' function expects a file-like object.\n        input_stream = io.StringIO(csv_content)\n        markdown_output = convert(input_stream)\n        print(markdown_output.strip())\n    except ImportError:\n        print(\"Error: 'csv2md' library not found. Please 'pip install csv2md'.\")\n    except Exception as e:\n        print(f\"Programmatic Error: {e}\")\n\nfinally:\n    if csv_file_path and os.path.exists(csv_file_path):\n        os.remove(csv_file_path)\n        print(f\"\\nCleaned up temporary CSV: {csv_file_path}\")","lang":"python","description":"This quickstart demonstrates both command-line and programmatic usage. It creates a temporary CSV file and then uses `csv2md` to convert it. For CLI usage, ensure `csv2md` is installed and in your system's PATH. For programmatic use, the `convert` function expects a file-like object (e.g., `io.StringIO`)."},"warnings":[{"fix":"Upgrade to `csv2md>=1.4.0` to ensure proper escaping of pipe characters in your Markdown tables.","message":"CSV cells containing pipe characters (`|`) were not escaped in Markdown output prior to `v1.4.0`, leading to malformed tables.","severity":"gotcha","affected_versions":"<1.4.0"},{"fix":"When using `convert` programmatically, pass an `io.StringIO(csv_string)` object or an opened file handle as input, not a string representing the file path.","message":"The `csv2md` library is primarily designed as a command-line tool. While programmatic use via `from csv2md import convert` is possible, the `convert` function expects a file-like object (like `io.StringIO` or an open file handle), not a file path string directly.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to `csv2md>=1.5.0` to ensure robust handling and ignoring of empty lines in your CSV input.","message":"Empty lines within CSV files were not consistently handled across all versions, potentially leading to errors or unexpected output. As of `v1.5.0`, empty lines are now properly ignored.","severity":"gotcha","affected_versions":"<1.5.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Run `pip install csv2md`. If the command still isn't found, ensure your pip script directory (e.g., `~/.local/bin` on Linux/macOS or `Scripts` folder in your Python install on Windows) is added to your system's PATH environment variable.","cause":"`csv2md` is not installed or the directory where `pip` installs scripts is not in your system's PATH.","error":"csv2md: command not found"},{"fix":"Upgrade your `csv2md` installation: `pip install --upgrade csv2md`. Version `1.4.0` and later include the fix for pipe escaping.","cause":"You are likely using an older version of `csv2md` that does not escape pipe characters in CSV cell values.","error":"Markdown table output is garbled or misaligned when CSV cells contain '|' characters."},{"fix":"Correct your programmatic call to include a file-like object: `from csv2md import convert; import io; markdown_output = convert(io.StringIO(your_csv_string_data))`.","cause":"When calling `csv2md.convert()` programmatically, you must pass a file-like object (such as `io.StringIO(csv_data)`) as the `input_csv_file` argument.","error":"TypeError: convert() missing 1 required positional argument: 'input_csv_file'"}]}