Jupyter Server 2.0 TZ environment variable affecting kernel timestamp inheritance

Answer to the exact questions

• Does changing os.environ['TZ'] inside a running kernel cell affect subsequent naive datetime calls? No, not automatically. datetime.datetime.now() relies on the C library’s time zone state, which is set once when the Python process starts. Changing TZ after that requires a re‑initialisation call.
• Are there scenarios where the server‑level TZ is ignored by scheduled nbconvert runs? Yes. If nbconvert is launched as a separate process (e.g., via a cron job, JupyterHub spawner, or a manual command line call), it inherits the environment of the shell that started it, not the Jupyter Server’s environment. In those cases, the server’s TZ setting is bypassed and the system default TZ is used.

Why the kernel doesn’t pick up the change

Python’s datetime module is a thin wrapper around the host operating system’s C time functions. When the interpreter starts, it calls tzset() (Unix only) to load the time zone information from the TZ variable. Subsequent calls to datetime.now() use that cached state. Simply assigning a new value to os.environ['TZ'] does not trigger a new tzset() call, so the kernel continues to use the original zone.

When nbconvert ignores the server TZ

• External launch: a cron job or a systemd service that runs jupyter nbconvert will use the environment of that service, not the Jupyter Server’s.
• Command‑line call: running jupyter nbconvert from a shell that hasn’t exported TZ will default to the system TZ.
• Containerised deployments: if the Jupyter Server runs inside a container, the container runtime may override or unset TZ, causing nbconvert (which inherits from the container) to use the host’s TZ.

Practical steps to get consistent timestamps

1. Verify the kernel’s TZ:

   %env TZ
   import os, datetime, time
   print('TZ in env:', os.environ.get('TZ'))
   print('Now:', datetime.datetime.now())
   

2. Apply a new TZ inside the kernel and re‑initialise time zone state (Unix only):

   import os, time
   os.environ['TZ'] = 'UTC'
   time.tzset()  # re‑initialise C library
   print('Now after tzset:', datetime.datetime.now())
   

   If you see the new zone reflected, the change worked.
3. Force the server to use a specific TZ for all kernels by adding the variable to the kernel’s kernel.json (or launching Jupyter with --env TZ=…):

   {
     "argv": ["python", "-m", "ipykernel_launcher", "-f", "{connection_file}"],
     "display_name": "Python 3",
     "env": {"TZ": "America/New_York"}
   }
   

   After restarting the kernel, the new TZ is part of the process environment from the start.
4. Ensure nbconvert inherits the desired TZ:
   • When launching nbconvert from the command line, prefix the command: TZ=America/New_York jupyter nbconvert --to html mynotebook.ipynb.
   • If using a scheduled job, export TZ in the job’s environment or pass it via the --env flag of the Jupyter spawner.
5. Verify the nbconvert process environment:

   ps -o pid,cmd -p $(pgrep -f "nbconvert")
   

   Check that TZ appears in the command line or environment dump.

What to ask next

To fine‑tune the recommendation, it would help to know the operating system you’re running (Unix vs Windows) because time.tzset() is not available on Windows. If you’re on Windows, the only way to change the zone for the current process is to restart the kernel with a new TZ in kernel.json or to set it before launching Jupyter.