Movatterモバイル変換

[0]ホーム
URL:

ContentsMenuExpandLight modeDark modeAuto light/dark, in light modeAuto light/dark, in dark modeSkip to content
setuptools 80.9.0 documentation
Logo

Links

Project

Back to top

Development Mode (a.k.a. “Editable Installs”)

When creating a Python project, developers usually want to implement and testchanges iteratively, before cutting a release and preparing a distribution archive.

In normal circumstances this can be quite cumbersome and require the developersto manipulate thePYTHONPATH environment variable or to continuously re-buildand re-install the project.

To facilitate iterative exploration and experimentation, setuptools allowsusers to instruct the Python interpreter and its import machinery to load thecode under development directly from the project folder without having tocopy the files to a different location in the disk.This means that changes in the Python source code can immediately take placewithout requiring a new installation.

You can enter this “development mode” by performing aneditable installation inside of avirtual environment,usingpip’s-e/--editable flag, as shown below:

$cdyour-python-project$python-mvenv.venv# Activate your environment with:#      `source .venv/bin/activate` on Unix/macOS# or   `.venv\Scripts\activate` on Windows$pipinstall--editable.# Now you have access to your package# as if it was installed in .venv$python-c"import your_python_project"

An “editable installation” works very similarly to a regular install withpipinstall., except that it only installs your package dependencies,metadata and wrappers forconsole and GUI scripts.Under the hood, setuptools will try to create a special.pthfilein the target directory (usuallysite-packages) that extends thePYTHONPATH or install a customimport hook.

When you’re done with a given development task, you can simply uninstall yourpackage (as you would normally do withpipuninstall<packagename>).

Please note that, by default an editable install will expose at least all thefiles that would be available in a regular installation. However, depending onthe file and directory organization in your project, it might also exposeas a side effect files that would not be normally available.This is allowed so you can iteratively create new Python modules.Please have a look on the following section if you are looking for a different behaviour.

Virtual Environments

You can think about virtual environments as “isolated Python runtime deployments”that allow users to install different sets of libraries and tools withoutmessing with the global behaviour of the system.

They are a safe way of testing new projects and can be created easilywith thevenv module from the standard library.

Please note however that depending on your operating system or distribution,venv might not come installed by default with Python. For those cases,you might need to use the OS package manager to install it.For example, in Debian/Ubuntu-based systems you can obtain it via:

sudoaptinstallpython3-venv

Alternatively, you can also try installingvirtualenv.More information is available on the Python Packaging User Guide onInstall packages in a virtual environment using pip and venv.

Note

Changed in version v64.0.0:Editable installation hooks implemented according toPEP 660.Support fornamespace packages is stillEXPERIMENTAL.

“Strict” editable installs

When thinking about editable installations, users might have the followingexpectations:

  1. It should allow developers to add new files (or split/rename existing ones)and have them automatically exposed.

  2. It should behave as close as possible to a regular installation and helpusers to detect problems (e.g. new files not being included in the distribution).

Unfortunately these expectations are in conflict with each other.To solve this problemsetuptools allows developers to choose a more“strict” mode for the editable installation. This can be done by passinga specialconfiguration setting viapip, as indicated below:

pipinstall-e.--config-settingseditable_mode=strict

In this mode, new fileswon’t be exposed and the editable installs willtry to mimic as much as possible the behavior of a regular install.Under the hood,setuptools will create a tree of file links in an auxiliarydirectory ($your_project_dir/build) and add it toPYTHONPATH via a.pthfile. (Please be careful to not delete this repositoryby mistake otherwise your files may stop being accessible).

Warning

Strict editable installs require auxiliary files to be placed in abuild/__editable__.* directory (relative to your project root).

Please be careful to not remove this directory while testing your project,otherwise your editable installation may be compromised.

You can remove thebuild/__editable__.* directory after uninstalling.

Note

Added in version v64.0.0:Added newstrict mode for editable installations.The exact details of how this mode is implemented may vary.

Limitations

  • Theeditable term is used to refer only to Python modulesinside the package directories. Non-Python files, external (data) files,executable script files, binary extensions, headers and metadata may beexposed as asnapshot of the version they were at the moment of theinstallation.

  • Adding new dependencies, entry-points or changing your project’s metadatarequire a fresh “editable” re-installation.

  • Console scripts and GUI scriptsMUST be specified viaentry-points to work properly.

  • Strict editable installs require the file system to supporteithersymbolic orhard links.This installation mode might also generate auxiliary files under the project directory.

  • There isno guarantee that the editable installation will be performedusing a specific technique. Depending on each project,setuptools mayselect a different approach to ensure the package is importable at runtime.

  • There isno guarantee that files outside the top-level package directorywill be accessible after an editable install.

  • There isno guarantee that attributes like__path__ or__file__will correspond to the exact location of the original files (e.g.,setuptools might employ file links to perform the editable installation).Users are encouraged to use tools likeimportlib.resources orimportlib.metadata when trying to access package files directly.

  • Editable installations may not work withnamespaces created with pkgutil or pkg_resources.Please usePEP 420-style implicit namespaces[1].

  • Support forPEP 420-style implicit namespace packages forprojects structured usingflat-layout is stillexperimental.If you experience problems, you can try converting your package structureto thesrc-layout.

  • File system entries in the current working directorywhose names coincidentally match installed packagesmay take precedence inPython’s import system.Users are encouraged to avoid such scenarios[2].

  • Setuptools will try to give the right precedence to modules in an editable install.However this is not always an easy task. If you have a particular order insys.path or some specific import precedence that needs to be respected,the editable installation as supported by Setuptools might not be able tofulfil this requirement, and therefore it might not be the right tool for your use case.

Attention

Editable installs arenot a perfect replacement for regular installsin a test environment. When in doubt, please test your projects asinstalled via a regular wheel. There are tools in the Python ecosystem,liketox ornox, that can help you with that(when used with appropriate configuration).

Legacy Behavior

If your project is not compatible with the new “editable installs” or you wishto replicate the legacy behavior, for the time being you can also perform theinstallation in thecompat mode:

pipinstall-e.--config-settingseditable_mode=compat

This installation mode will try to emulate howpythonsetup.pydevelopworks (still within the context ofPEP 660).

Warning

Thecompat mode istransitional and will be removed infuture versions ofsetuptools, it exists only to help during themigration period.Also note that support for this mode is limited:it is safe to assume that thecompat mode is offered “as is”, andimprovements are unlikely to be implemented.Users are encouraged to try out the new editable installation techniquesand make the necessary adaptations.

How editable installations work

Advanced topic

There are many techniques that can be used to expose packages under developmentin such a way that they are available as if they were installed.Depending on the project file structure and the selected mode,setuptoolswill choose one of these approaches for the editable installation[3].

A non-exhaustive list of implementation mechanisms is presented below.More information is available on the text ofPEP 660.

Attention

Setuptools offersno guarantee of which technique will be used toperform an editable installation. This will vary from project to projectand may change depending on the specific version ofsetuptools beingused.

Debugging Tips

If encountering problems installing a project in editable mode,follow these recommended steps to help debug:

  • Try to install the project normally, without using the editable mode.Does the error still persist?(If it does, try fixing the problem before attempting the editable mode).

  • When using binary extensions, make sure all OS-leveldependencies are installed (e.g. compilers, toolchains, binary libraries, …).

  • Try the latest version of setuptools (maybe the error was already fixed).

  • When the project or its dependencies are using any setuptools extensionor customization, make sure they support the editable mode.

After following the steps above, if the problem still persists andyou think this is related to how setuptools handles editable installations,please submit areproducible example atthe bug tracker.

Notes

[1]

Youmay be able to usestrict editable installations with namespacepackages created withpkgutil orpkg_namespaces, however this is notofficially supported.

[2]

Techniques like thesrc-layout or tooling-specific options liketox’s changedircan be used to prevent such kinds of situations (checkoutthis blog post for moreinsights).

[3]

setuptools strives to find a balance between allowing the user to seethe effects of project files being edited while still trying to keep theeditable installation as similar as possible to a regular installation.

[4]

i.e., a.pth file where each line correspond to a path that should beadded tosys.path. SeeSite-specificconfigurationhook.

[5]

i.e., a.pth file that starts where each line starts with animportstatement and executes arbitrary Python code. SeeSite-specificconfigurationhook.

On this page
[8]ページ先頭
©2009-2025 Movatter.jp