{"id":4594,"library":"jupyter-packaging","title":"Jupyter Packaging Utilities","description":"Jupyter Packaging provides utility functions and `setuptools` build command classes to simplify the packaging of Jupyter applications and extensions, particularly those with front-end (JavaScript/TypeScript) assets. It helps integrate pre-build steps into the Python packaging process. The current version is 0.12.3, and it typically sees releases for bug fixes, maintenance, and enhancements related to packaging standards and dependencies.","status":"active","version":"0.12.3","language":"en","source_language":"en","source_url":"https://github.com/jupyter/jupyter-packaging/","tags":["jupyter","packaging","setuptools","build","frontend","extension"],"install":[{"cmd":"pip install jupyter-packaging","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core build dependency for integrating with Python packaging.","package":"setuptools","optional":false},{"reason":"Required for building front-end (JavaScript/TypeScript) assets for Jupyter extensions.","package":"Node.js/npm/yarn","optional":true}],"imports":[{"note":"Used to wrap setuptools commands like 'install' or 'develop' with pre- and post-build steps.","symbol":"wrap_installers","correct":"from jupyter_packaging import wrap_installers"},{"note":"A utility builder class for executing Node.js package manager commands (npm or yarn) as part of the build process.","symbol":"npm_builder","correct":"from jupyter_packaging import npm_builder"},{"note":"As of `setuptools` v61.0.0, `bdist_wheel` moved from the `wheel` package into `setuptools` itself. `jupyter-packaging` v0.12.0 updated its internal import path to reflect this, but older versions of `jupyter-packaging` might break if used with newer `setuptools` versions.","wrong":"from wheel.bdist_wheel import bdist_wheel","symbol":"bdist_wheel","correct":"from setuptools.command.bdist_wheel import bdist_wheel"}],"quickstart":{"code":"from setuptools import setup\ntry:\n    from jupyter_packaging import wrap_installers, npm_builder\n    \n    # Define the builder for npm commands\n    # Assumes a package.json in the root that defines 'build' and 'build:dev' scripts\n    builder = npm_builder(build_cmd='build', develop_cmd='build:dev')\n    \n    # Wrap the 'install' and 'develop' commands with the npm builder\n    cmdclass = wrap_installers(pre_develop=builder, pre_dist=builder)\nexcept ImportError:\n    # Fallback for when jupyter_packaging is not available (e.g., during sdist build)\n    cmdclass = {}\n\nsetup(\n    name='my_jupyter_extension',\n    version='0.1.0',\n    cmdclass=cmdclass,\n    # Other setup arguments like packages, include_package_data, etc.\n    packages=['my_jupyter_extension'],\n    include_package_data=True,\n    # Make sure to include MANIFEST.in for data files not in Python packages\n    # (e.g., JS/CSS assets, Jupyter config files)\n)","lang":"python","description":"This quickstart demonstrates how to integrate `jupyter-packaging` into a `setup.py` file to handle front-end build steps for a Jupyter extension. It uses `npm_builder` to define pre-build commands for both development (`develop`) and distribution (`dist`) modes, ensuring that JavaScript/TypeScript assets are compiled before the Python package is installed or built. The `try/except ImportError` block allows the `setup.py` to be run even if `jupyter-packaging` is not installed, which can be useful during initial `sdist` creation or local testing."},"warnings":[{"fix":"Upgrade `jupyter-packaging` to version 0.12.0 or later. Ensure your `setup.py` or `pyproject.toml` specifies a compatible `jupyter-packaging` version.","message":"When upgrading `setuptools` to version 61.0.0 or higher, projects using `jupyter-packaging` versions prior to 0.12.0 may encounter `ImportError` due to a change in the internal import path for `bdist_wheel`.","severity":"breaking","affected_versions":"<0.12.0"},{"fix":"Ensure your project targets Python 3.7 or newer. Upgrade your Python environment if necessary.","message":"Support for Python 3.6 was dropped with the release of `jupyter-packaging` 0.11.0.","severity":"deprecated","affected_versions":"<0.11.0"},{"fix":"Install Node.js (which includes npm) and optionally yarn in your build environment. Verify their availability by running `node -v` and `npm -v` (or `yarn -v`).","message":"Building Jupyter extensions with front-end assets typically requires Node.js and a package manager (npm or yarn) to be installed and available in the system's PATH, as `jupyter-packaging` will execute these tools.","severity":"gotcha","affected_versions":"All"},{"fix":"Configure `jupyter-packaging` as a build requirement in your `pyproject.toml` (e.g., `requires = [\"jupyter_packaging>=0.10,<2\"]`) or ensure it's only installed in build environments.","message":"`jupyter-packaging` is primarily intended as a *build-time* dependency, not a *runtime* dependency. It should be listed in `build-system.requires` in `pyproject.toml` rather than `install_requires` in `setup.py` or `dependencies` in `pyproject.toml` for most projects.","severity":"gotcha","affected_versions":"All"},{"fix":"Instead of `python setup.py sdist` or `python setup.py bdist_wheel`, use `pip install build` followed by `python -m build .`.","message":"`jupyter-packaging` does not support the deprecated `python setup.py bdist_wheel` or `python setup.py sdist` commands directly. The recommended approach for building distributions is to use the `build` package.","severity":"gotcha","affected_versions":"All"},{"fix":"For development installations, you might need to perform a full install (`pip install .`) before an editable install (`pip install -e .`), or manually link/copy data files into the appropriate locations.","message":"Setuptools' `data_files` (often used for Jupyter configuration files) are not fully supported in editable (`pip install -e .`) mode.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}