Changes in Jupyter Client {#changelog}


(Full Changelog)

Enhancements made

Bugs fixed

Maintenance and upkeep improvements

Contributors to this release

(GitHub contributors page for this release)

@blink1073 | @ci4ic4 | @davidbrochart | @kevin-bates | @vidartf


(Full Changelog)

Bugs fixed

  • Fallback to the old ipykernel “json_clean” if we are not able to serialize a JSON message #708 (@martinRenou)

Other merged PRs

Contributors to this release

(GitHub contributors page for this release)



(Full Changelog)

Bugs fixed

  • avoid use of deprecated zmq.utils.jsonapi #703 (@minrk)

Maintenance and upkeep improvements

Contributors to this release

(GitHub contributors page for this release)

@kevin-bates | @minrk


(Full Changelog)

Bugs fixed

Contributors to this release

(GitHub contributors page for this release)

@davidbrochart | @martinRenou | @mofanke | @shingo78


(Full Changelog)

Bugs fixed

  • Address missing local-provisioner scenario #692 (@kevin-bates)

  • use load_connection_info(info) when constructing a blocking client #688 (@minrk)

Contributors to this release

(GitHub contributors page for this release)

@kevin-bates | @minrk


(Full Changelog)

Bugs fixed

  • Don’t set event loop policy on Windows at import time #686 (@minrk)

Documentation improvements

Contributors to this release

(GitHub contributors page for this release)

@blink1073 | @davidbrochart | @dhirschfeld | @jankatins | @kevin-bates | @minrk | @takluyver | @yuvipanda


(Full Changelog)

Merged PRs

Contributors to this release

(GitHub contributors page for this release)



(Full Changelog)


The 7.0 release brings a major feature in Kernel Provisioners, which enable the ability for third parties to manage the lifecycle of a kernel’s runtime environment.

Being a major release, there are some backward incompatible changes. Please see the migration guide for further details.

Enhancements made

Bugs fixed

Maintenance and upkeep improvements

Documentation improvements

Contributors to this release

(GitHub contributors page for this release)

@afshin | @blink1073 | @Carreau | @ccordoba12 | @davidbrochart | @dhirschfeld | @dolfinus | @echarles | @impact27 | @JohanMabille | @kevin-bates | @martinRenou | @mattip | @minrk | @MSeal | @SylvainCorlay | @takluyver | @vidartf | @yitzchak


  • Yanked (PyPI) and marked as broken (conda)


  • Yanked (PyPI) and marked as broken (conda)


  • Shutdown request sequence has been modified to be more graceful, it now is preceded by interrupt, and will also send a SIGTERM before forcibly killing the kernel. #620

  • Removal of ipython_genutils as a dependency. It was implicit before; but required by at least traitlets thus avoiding issues. We are working on completely removing it from all jupyter dependencies; as it might lead to issues packaging for Python 3.10, and was mostly used for compatibility with python 2. (#620, #605)

  • Address a race condition between shutdown_kernel and restarter. (#607.)

See the full list of pull-requests


  • Move jedi pinning to test requirements #599


  • Add change parameter needed for observer method of kernel_spec_manager trait #598


  • Pin jedi<=0.17.2 #596


  • Doc updates (#563, #564, #587)

  • Fix path to the connection file #568

  • Code cleanup (#574, #579)

  • Silence kill_kernel when no process is present #576

  • Remove extra_env and corresponding test #581

  • Add documentation dependencies to #582

  • Fix for Windows localhost IP addresses #584

  • Drop Travis CI, add GitHub Actions #586

  • Adapt KernelManager._kernel_spec_manager_changed to observe #588

  • Allow use ~/ in the kernel’s command or its arguments #589

  • Change wait_for_ready logic #592

  • Fix test_session with msgpack v1 #594


  • Removed warnings in more cases for KernelManagers that use new cleanup method #560

  • Some improved tests with a conversion to pytest pattern #561


  • Gracefully Close ZMQ Context upon kernel shutdown to fix memory leak #548

  • Fix for chained exceptions to preserve stacks (#552, #554)

  • Fix start_kernel error when passing kernel_id #547

  • Update to releasing docs #543


(Deleted release with incorrect local files)


  • Add AsyncKernelClient client_class to AsyncKernelManager #542

  • Doc fix for xeus hyperlinks #540

  • Doc typo fix #539


  • Fixed a bug causing clients to sometimes hang after a stop call was made #536


  • Subprocess kill action fix for async execution #535

  • Doc fix for xeus kernel list #534


This release includes support for asyncio patterns! Downstream tools should soon have releases to additionally support async patterns.

  • AsyncKernelManager and AsyncMultiKernelManager are now available for async jupyter_client interactions (#528, #529)

  • Removed unused sphinx dependency (#518, #518).

  • Added install instructions for pip to documentation #521

  • Improved docs around version protocol and messaging (#522, #526)


The git history had to be reworked heavily in merging 5.x and master, so a link to all the changes at once in github had been left out as it’s just confusing.

An exciting change in this release is some async support (huge thanks to @davidbrochart for doing most of the work)! See linked PR below for more details, we’re working on integrating this into nbclient as well in the near future.

New Features:

  • Added async API #506


  • Python 3.8 testing and support added #509

  • Session.msg_id optimization #493

  • Only cache ports if the cache_ports flag is set to True #492

  • Removed direct dependency on pywin32 as this is now in jupyter core #489


  • Prevent two kernels to have the same ports #490


  • Document the handling of error in do_execute #500

Breaking changes:

  • Dropped support for Python 2.7!



  • Changed secure_write to be imported from jupyter_core with fix for extended usernames in Windows #483.


  • Fixed issue with non-english windows permissions #478. Potential issue still open in use with jupyerlab.


  • Important files creation now checks umask permissions #469.


  • Fix bug with control channel socket introduced in 5.3.0 #456.


5.3.0 on GitHub

New Features:

  • Multiprocessing and Threading support #437 and #450

  • Setup package long_description #411


  • Control channel now in the public API #447

  • Closing Jupyter Client is now faster #420

  • Pip support improvements #421

Breaking changes:

  • Dropped support for Python 3.3 and 3.4 (upstream packages dropped support already)


5.2.4 on GitHub

  • Prevent creating new console windows on Windows #346

  • Fix interrupts on Python 3.7 on Windows #408


5.2.3 on GitHub

  • Fix hang on close in .ThreadedKernelClient (used in QtConsole) when using tornado with asyncio (default behavior of tornado 5, see #352).

  • Fix errors when using deprecated .KernelManager.kernel_cmd (#343, #344).


5.2.2 on GitHub

  • Fix .KernelSpecManager.get_all_specs method in subclasses that only override .KernelSpecManager.find_kernel_specs and .KernelSpecManager.get_kernel_spec. See #338 and #339.

  • Eliminate occasional error messages during process exit #336.

  • Improve error message when attempting to bind on invalid address #330.

  • Add missing direct dependency on tornado #323.


5.2.1 on GitHub

  • Add parenthesis to conditional pytest requirement to work around a bug in the wheel package, that generate a .whl which otherwise always depends on pytest see #324and #325.


5.2 on GitHub

  • Define Jupyter protocol version 5.3:

    • Kernels can now opt to be interrupted by a message sent on the control channel instead of a system signal. See kernelspecs and msging_interrupt #294.

  • New jupyter kernel command to launch an installed kernel by name #240.

  • Kernelspecs where the command starts with e.g. python3 or python3.6—matching the version jupyter_client is running on—are now launched with the same Python executable as the launching process #306. This extends the special handling of python added in 5.0.

  • Command line arguments specified by a kernelspec can now include {resource_dir}, which will be substituted with the kernelspec resource directory path when the kernel is launched #289.

  • Kernelspecs now have an optional metadata field to hold arbitrary metadata about kernels—see kernelspecs #274.

  • Make the KernelRestarter class used by a KernelManager configurable #290.

  • When killing a kernel on Unix, kill its process group #314.

  • If a kernel dies soon after starting, reassign random ports before restarting it, in case one of the previously chosen ports has been bound by another process #279.

  • Avoid unnecessary filesystem operations when finding a kernelspec with .KernelSpecManager.get_kernel_spec #311.

  • .KernelSpecManager.get_all_specs will no longer raise an exception on encountering an invalid kernel.json file. It will raise a warning and continue #310.

  • Check for non-contiguous buffers before trying to send them through ZMQ #258.

  • Compatibility with upcoming Tornado version 5.0 #304.

  • Simplify setup code by always using setuptools #284.

  • Soften warnings when setting the sticky bit on runtime files fails #286.

  • Various corrections and improvements to documentation.


5.1 on GitHub

  • Define Jupyter protocol version 5.2, resolving ambiguity of cursor_pos field in the presence of unicode surrogate pairs.

    ::: {.seealso} cursor_pos_unicode_note :::

  • Add Session.clone for making a copy of a Session object without sharing the digest history. Reusing a single Session object to connect multiple sockets to the same IOPub peer can cause digest collisions.

  • Avoid global references preventing garbage collection of background threads.



5.0.1 on GitHub

  • Update internal protocol version number to 5.1, which should have been done in 5.0.0.


5.0.0 on GitHub

New features:

  • Implement Jupyter protocol version 5.1.

  • Introduce jupyter run command for running scripts with a kernel, for instance:

    jupyter run --kernel python3
  • New method .BlockingKernelClient.execute_interactive for running code and capturing or redisplaying its output.

  • New KernelManager.shutdown_wait_time configurable for adjusting the time for a kernel manager to wait after politely requesting shutdown before it resorts to forceful termination.


  • Set sticky bit on connection-file directory to avoid getting cleaned up.

  • jupyter_client.launcher.launch_kernel passes through additional options to the underlying Popen, matching KernelManager.start_kernel.

  • Check types of buffers argument in .Session.send, so that TypeErrors are raised immediately, rather than in the eventloop.


  • In kernelspecs, if the executable is the string python (as opposed to an absolute path), sys.executable will be used rather than resolving python on PATH. This should enable Python-based kernels to install kernelspecs as part of wheels.

  • kernelspec names are now validated. They should only include ascii letters and numbers, plus period, hyphen, and underscore.

Backward-incompatible changes:

  • :py.datetime objects returned in parsed messages are now always timezone-aware. Timestamps in messages without timezone info are interpreted as the local timezone, as this was the behavior in earlier versions.



4.4 on GitHub

  • Add .KernelClient.load_connection_info on KernelClient, etc. for loading connection info directly from a dict, not just from files.

  • Include parent headers when adapting messages from older protocol implementations (treats parent headers the same as headers).

  • Compatibility fixes in tests for recent changes in ipykernel.



4.3 on GitHub

  • Adds --sys-prefix argument to jupyter kernelspec install, for better symmetry with jupyter nbextension install, etc.



4.2.2 on GitHub

  • Another fix for the start_new_kernel issue in 4.2.1 affecting slow-starting kernels.


4.2.1 on GitHub

  • Fix regression in 4.2 causing start_new_kernel to fail while waiting for kernels to become available.


4.2.0 on GitHub

  • added jupyter kernelspec remove for removing kernelspecs

  • allow specifying the environment for kernel processes via the env argument

  • added name field to connection files identifying the kernelspec name, so that consumers of connection files (alternate frontends) can identify the kernelspec in use

  • added KernelSpecManager.get_all_specs for getting all kernelspecs more efficiently

  • various improvements to error messages and documentation



4.1.0 on GitHub


  • Setuptools fixes for jupyter kernelspec

  • jupyter kernelspec list includes paths

  • add KernelManager.blocking_client

  • provisional implementation of comm_info requests from upcoming 5.1 release of the protocol


The first release of Jupyter Client as its own package.