{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# IPython/Jupyter magic function documentation - `%watermark`" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "I wrote this simple `watermark` IPython magic function to conveniently add date- and time-stamps to my IPython notebooks. Also, I often want to document various system information, e.g., for my [Python benchmarks](https://github.com/rasbt/One-Python-benchmark-per-day) series.\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ " \n", "## Installation" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The watermark line magic can be installed by executing\n", "\n", "```bash\n", "pip install watermark\n", "```\n", "\n", "Alternatively, you can install the latest development version directly from GitHub via\n", "\n", "```bash\n", "pip install -e git+https://github.com/rasbt/watermark#egg=watermark\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ " \n", "## Loading the `%watermark` magic" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "To load the `watermark` magic, execute the following line in your IPython notebook or current IPython shell" ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "%load_ext watermark" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The version of `watermark` itself can be retrieved as follows:" ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Watermark: 2.5.1\n", "\n" ] } ], "source": [ "%watermark --watermark" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ " \n", "## Usage" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "In order to display the optional `watermark` arguments, type" ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\u001b[31mDocstring:\u001b[39m\n", "::\n", "\n", " %watermark [-a AUTHOR] [-gu GITHUB_USERNAME] [-e EMAIL] [-ws WEBSITE]\n", " [-d] [-n] [-t] [-i] [-z] [-u] [-c CUSTOM_TIME] [-v]\n", " [-p PACKAGES] [-co] [-h] [-m] [-g] [-r] [-b] [-w] [-iv]\n", " [--gpu] [-je] [--python_installation] [--check_latest]\n", "\n", "IPython magic function to print date/time stamps\n", "and various system information.\n", "\n", "options:\n", " -a AUTHOR, --author AUTHOR\n", " prints author name\n", " -gu GITHUB_USERNAME, --github_username GITHUB_USERNAME\n", " prints author github username\n", " -e EMAIL, --email EMAIL\n", " prints author email\n", " -ws WEBSITE, --website WEBSITE\n", " prints author or project website\n", " -d, --date prints current date as YYYY-mm-dd\n", " -n, --datename prints date with abbrv. day and month names\n", " -t, --time prints current time as HH-MM-SS\n", " -i, --iso8601 prints the combined date and time including the time\n", " zone in the ISO 8601 standard with UTC offset\n", " -z, --timezone appends the local time zone\n", " -u, --updated appends a string \"Last updated: \"\n", " -c CUSTOM_TIME, --custom_time CUSTOM_TIME\n", " prints a valid strftime() string\n", " -v, --python prints Python and IPython version\n", " -p PACKAGES, --packages PACKAGES\n", " prints versions of specified Python modules and\n", " packages\n", " -co, --conda prints name of current conda environment\n", " -h, --hostname prints the host name\n", " -m, --machine prints system and machine info\n", " -g, --githash prints current Git commit hash\n", " -r, --gitrepo prints current Git remote address\n", " -b, --gitbranch prints current Git branch\n", " -w, --watermark prints the current version of watermark\n", " -iv, --iversions prints the name/version of all imported modules\n", " --gpu prints GPU information (currently limited to NVIDIA\n", " GPUs), if available\n", " -je, --jupyter_env prints the current Jupyter environment (e.g., Colab,\n", " VS Code)\n", " --python_installation\n", " include information about how Python was installed\n", " --check_latest check if the latest packages are installed\n", "\u001b[31mFile:\u001b[39m ~/Desktop/watermark/watermark/magic.py" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "%watermark?" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "
\n",
    "%watermark [-a AUTHOR] [-gu GITHUB_USERNAME] [-e EMAIL] [-ws WEBSITE]\n",
    "                 [-d] [-n] [-t] [-i] [-z] [-u] [-c CUSTOM_TIME] [-v]\n",
    "                 [-p PACKAGES] [-h] [-m] [-g] [-r] [-b] [-w] [-iv]\n",
    "\n",
    "IPython magic function to print date/time stamps\n",
    "and various system information.\n",
    "\n",
    "options:\n",
    "  -a AUTHOR, --author AUTHOR\n",
    "                        prints author name\n",
    "  -gu GITHUB_USERNAME, --github_username GITHUB_USERNAME\n",
    "                        prints author github username\n",
    "  -e EMAIL, --email EMAIL\n",
    "                        prints author email\n",
    "  -ws WEBSITE, --website WEBSITE\n",
    "                        prints author or project website\n",
    "  -d, --date            prints current date as YYYY-mm-dd\n",
    "  -n, --datename        prints date with abbrv. day and month names\n",
    "  -t, --time            prints current time as HH-MM-SS\n",
    "  -i, --iso8601         prints the combined date and time including the time\n",
    "                        zone in the ISO 8601 standard with UTC offset\n",
    "  -z, --timezone        appends the local time zone\n",
    "  -u, --updated         appends a string \"Last updated: \"\n",
    "  -c CUSTOM_TIME, --custom_time CUSTOM_TIME\n",
    "                        prints a valid strftime() string\n",
    "  -v, --python          prints Python and IPython version\n",
    "  -p PACKAGES, --packages PACKAGES\n",
    "                        prints versions of specified Python modules and\n",
    "                        packages\n",
    "  -h, --hostname        prints the host name\n",
    "  -m, --machine         prints system and machine info\n",
    "  -g, --githash         prints current Git commit hash\n",
    "  -r, --gitrepo         prints current Git remote address\n",
    "  -b, --gitbranch       prints current Git branch\n",
    "  -w, --watermark       prints the current version of watermark\n",
    "  -iv, --iversions      prints the name/version of all imported modules\n",
    "
" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ " \n", "## Examples" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ " \n", "### Defaults" ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Last updated: 2025-12-21T17:20:40.483494-06:00\n", "\n", "Python implementation: CPython\n", "Python version : 3.13.5\n", "IPython version : 9.8.0\n", "\n", "Compiler : Clang 20.1.4 \n", "OS : Darwin\n", "Release : 24.6.0\n", "Machine : arm64\n", "Processor : arm\n", "CPU cores : 12\n", "Architecture: 64bit\n", "\n" ] } ], "source": [ "%watermark" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ " \n", "### Last updated date and time" ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Last updated: 2025-12-21 17:20:40\n", "\n" ] } ], "source": [ "%watermark -u -t -d" ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Last updated: 2025-12-21T17:20:40.494820-06:00\n", "\n" ] } ], "source": [ "%watermark -u --iso8601" ] }, { "cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Last updated: Sun, 21 Dec 2025 17:20:40 CST\n", "\n" ] } ], "source": [ "%watermark -u -n -t -z" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ " \n", "### Python version information" ] }, { "cell_type": "code", "execution_count": 8, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Python implementation: CPython\n", "Python version : 3.13.5\n", "IPython version : 9.8.0\n", "\n" ] } ], "source": [ "%watermark -v" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ " \n", "### Machine information" ] }, { "cell_type": "code", "execution_count": 9, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Compiler : Clang 20.1.4 \n", "OS : Darwin\n", "Release : 24.6.0\n", "Machine : arm64\n", "Processor : arm\n", "CPU cores : 12\n", "Architecture: 64bit\n", "\n" ] } ], "source": [ "%watermark -m" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ " \n", "### Combination of information" ] }, { "cell_type": "code", "execution_count": 10, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Python implementation: CPython\n", "Python version : 3.13.5\n", "IPython version : 9.8.0\n", "\n", "numpy : 2.4.0\n", "scipy : 1.16.3\n", "sklearn: 1.8.0\n", "\n", "Compiler : Clang 20.1.4 \n", "OS : Darwin\n", "Release : 24.6.0\n", "Machine : arm64\n", "Processor : arm\n", "CPU cores : 12\n", "Architecture: 64bit\n", "\n" ] } ], "source": [ "%watermark -v -m -p numpy,scipy,sklearn " ] }, { "cell_type": "markdown", "metadata": {}, "source": [ " \n", "### With author" ] }, { "cell_type": "code", "execution_count": 11, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Author: John Doe\n", "\n", "Last updated: 2025-12-21\n", "\n", "Python implementation: CPython\n", "Python version : 3.13.5\n", "IPython version : 9.8.0\n", "\n", "Compiler : Clang 20.1.4 \n", "OS : Darwin\n", "Release : 24.6.0\n", "Machine : arm64\n", "Processor : arm\n", "CPU cores : 12\n", "Architecture: 64bit\n", "\n" ] } ], "source": [ "%watermark -a \"John Doe\" -u -d -v -m" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ " \n", "### Imported modules information" ] }, { "cell_type": "code", "execution_count": 12, "metadata": {}, "outputs": [], "source": [ "import scipy as sp\n", "from sklearn import metrics\n", "import numpy.linalg as linalg" ] }, { "cell_type": "code", "execution_count": 13, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "numpy : 2.4.0\n", "scipy : 1.16.3\n", "sklearn: 1.8.0\n", "\n" ] } ], "source": [ "%watermark --iversions" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ " \n", "### Jupyter environment information" ] }, { "cell_type": "code", "execution_count": 14, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "numpy : 2.4.0\n", "scipy : 1.16.3\n", "sklearn: 1.8.0\n", "\n", "Jupyter enviroment: JupyterLab\n", "\n" ] } ], "source": [ "%watermark -p numpy,scipy,sklearn --jupyter_env" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ " \n", "### Information about how Python was installed" ] }, { "cell_type": "code", "execution_count": 15, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "numpy : 2.4.0\n", "scipy : 1.16.3\n", "sklearn: 1.8.0\n", "\n", "Python installation: Virtual Environment (venv/virtualenv)\n", "\n" ] } ], "source": [ "%watermark -p numpy,scipy,sklearn --python_installation" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ " \n", "### Check if latest packages are installed" ] }, { "cell_type": "code", "execution_count": 16, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\u001b[2mUsing Python 3.13.5 environment at: /Users/sebastian/Desktop/watermark/.venv\u001b[0m\n", "\u001b[2K\u001b[2mResolved \u001b[1m1 package\u001b[0m \u001b[2min 727ms\u001b[0m\u001b[0m \u001b[0m\n", "\u001b[2K\u001b[2mPrepared \u001b[1m1 package\u001b[0m \u001b[2min 723ms\u001b[0m\u001b[0m \n", "\u001b[2mUninstalled \u001b[1m1 package\u001b[0m \u001b[2min 55ms\u001b[0m\u001b[0m\n", "\u001b[2K\u001b[2mInstalled \u001b[1m1 package\u001b[0m \u001b[2min 6ms\u001b[0m\u001b[0m \u001b[0m\n", " \u001b[31m-\u001b[39m \u001b[1mnumpy\u001b[0m\u001b[2m==2.4.0\u001b[0m\n", " \u001b[32m+\u001b[39m \u001b[1mnumpy\u001b[0m\u001b[2m==2.3.0\u001b[0m\n" ] } ], "source": [ "!uv pip install numpy==2.3.0" ] }, { "cell_type": "code", "execution_count": 17, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "numpy : 2.3.0 (version 2.4.0 is available)\n", "scipy : 1.16.3\n", "sklearn: 1.8.0 (version 0.0.post12 is available)\n", "\n" ] } ], "source": [ "%watermark -p numpy,scipy,sklearn --check_latest" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.13.5" }, "toc": { "base_numbering": 1, "nav_menu": {}, "number_sections": true, "sideBar": true, "skip_h1_title": false, "title_cell": "Table of Contents", "title_sidebar": "Contents", "toc_cell": false, "toc_position": {}, "toc_section_display": true, "toc_window_display": false } }, "nbformat": 4, "nbformat_minor": 4 }