package lwt

  1. Overview
  2. Docs
Promises and event-driven I/O

Install 

dune-project
 Dependency

github.com Readme MIT License Edit opam file Versions (33)

Authors

  1. J
    Jérôme Vouillon
  2. J
    Jérémie Dimino

Maintainers

  1. R
    Raphaël Proust <code@bnwr.net>
  2. Anton Bachin

Sources

6.0.0-beta01.tar.gz
md5=6bb978c590433a218a53722b985a01d4
sha512=529c8c920716cf204efd60a2bad3f817eed6eed120a8e8a8dae763ab7f4c45799a74004d0d0a2b8ec08f37c81b77f1a4813426a25f256b254dfa846c86debe44

Description

A promise is a value that may become determined in the future.

Lwt provides typed, composable promises. Promises that are resolved by I/O are resolved by Lwt in parallel.

Meanwhile, OCaml code, including code creating and waiting on promises, runs in a single thread by default. This reduces the need for locks or other synchronization primitives. Code can be run in parallel on an opt-in basis.

Published: 05 Feb 2026

README

Lwt

version GitHub Actions status

Lwt is a concurrent programming library for OCaml. It provides a single data type: the promise, which is a value that will become determined in the future. Creating a promise spawns a computation. When that computation is I/O, Lwt runs it in parallel with your OCaml code.

OCaml code, including creating and waiting on promises, is run in a single thread by default, so you don't have to worry about locking or preemption. You can detach code to be run in separate threads on an opt-in basis.

Here is a simplistic Lwt program which requests the Google front page, and fails if the request is not completed in five seconds:

open Lwt.Syntax

let () =
  let request =
    let* addresses = Lwt_unix.getaddrinfo "google.com" "80" [] in
    let google = Lwt_unix.((List.hd addresses).ai_addr) in

    Lwt_io.(with_connection google (fun (incoming, outgoing) ->
      let* () = write outgoing "GET / HTTP/1.1\r\n" in
      let* () = write outgoing "Connection: close\r\n\r\n" in
      let* response = read incoming in
      Lwt.return (Some response)))
  in

  let timeout =
    let* () = Lwt_unix.sleep 5. in
    Lwt.return None
  in

  match Lwt_main.run (Lwt.pick [request; timeout]) with
  | Some response -> print_string response
  | None -> prerr_endline "Request timed out"; exit 1

(* ocamlfind opt -package lwt.unix -linkpkg example.ml && ./a.out *)

In the program, functions such as Lwt_io.write create promises. The let* ... in construct is used to wait for a promise to become determined; the code after in is scheduled to run in a "callback." Lwt.pick races promises against each other, and behaves as the first one to complete. Lwt_main.run forces the whole promise-computation network to be executed. All the visible OCaml code is run in a single thread, but Lwt internally uses a combination of worker threads and non-blocking file descriptors to resolve in parallel the promises that do I/O.


Overview

Lwt compiles to native code on Linux, macOS, Windows, and other systems. It's also routinely compiled to JavaScript for the front end and Node by js_of_ocaml.

In Lwt,

  • The core library Lwt provides promises...
  • ...and a few pure-OCaml helpers, such as promise-friendly mutexes, condition variables, and mvars.
  • There is a big Unix binding, Lwt_unix that binds almost every Unix system call. A higher-level module Lwt_io provides nice I/O channels.
  • Lwt_process is for subprocess handling.
  • Lwt_preemptive spawns system threads.
  • The PPX syntax allows using all of the above without going crazy!
  • There are also some other helpers, such as Lwt_react for reactive programming. See the table of contents on the linked manual pages!

Installing

  1. Use your system package manager to install a development libev package. It is often called libev-dev or libev-devel.
  2. opam install conf-libev lwt

Documentation

We are currently working on improving the Lwt documentation (drastically; we are rewriting the manual). In the meantime:

  • The current manual can be found here.
  • Mirage has a nicely-written Lwt tutorial.
  • An example of a simple server written in Lwt.
  • Concurrent Programming with Lwt is a nice source of Lwt examples. They are translations of code from the excellent Real World OCaml, but are just as useful if you are not reading the book.

Note: much of the current manual refers to 'a Lwt.t as "lightweight threads" or just "threads." This will be fixed in the new manual. 'a Lwt.t is a promise, and has nothing to do with system or preemptive threads.


Contact

Open an issue, visit Discord chat, ask on discuss.ocaml.org, or on Stack Overflow.

Release announcements are made on discuss.ocaml.org. Watching the repo for "Releases only" is also an option.


Contributing

  • CONTRIBUTING.md contains tips for working on the code, such as how to check the code out, how review works, etc. There is also a high-level outline of the code base.
  • Ask us anything, whether it's about working on Lwt, or any question at all about it :)
  • The documentation always needs proofreading and fixes.
  • You are welcome to pick up any other issue, review a PR, add your opinion, etc.
  • Any feedback is welcome, including how to make contributing easier!

Libraries to use with Lwt

Dependencies (5)

  1. ocplib-endian
  2. dune-configurator
  3. cppo build & >= "1.1"
  4. ocaml >= "4.14" & < "5.5"
  5. dune >= "3.15"

Dev Dependencies (2)

  1. odoc with-doc & >= "2.3"
  2. ocamlfind with-dev-setup & >= "1.7.3-1"

  1. 0install >= "2.15.1"
  2. aches-lwt
  3. activitypub
  4. albatross
  5. alcotest-lwt
  6. alcotest-mirage
  7. ambient-context-lwt
  8. amqp-client >= "1.1.0"
  9. amqp-client-lwt
  10. angstrom-lwt-unix >= "0.11.0"
  11. anthill
  12. anycache-lwt
  13. archi-lwt
  14. arp
  15. awa-mirage
  16. aws-lwt
  17. aws-s3-lwt >= "4.8.1"
  18. awskit-lwt
  19. awskit-lwt-unix
  20. awskit-s3-lwt
  21. awskit-s3-lwt-unix
  22. awsm-lwt
  23. awso-lwt
  24. azure-cosmos-db < "0.4.0"
  25. azure-cosmos-db-lwt
  26. balancer
  27. bastet_lwt
  28. bimage-lwt
  29. bistro
  30. bizowie-api
  31. brisk-reconciler
  32. builder
  33. builder-web
  34. bun >= "0.3.3"
  35. cachet-lwt
  36. calculon
  37. caldav
  38. camltc
  39. canary
  40. capnp-rpc-lwt < "2.0"
  41. capnp-rpc-unix < "2.1"
  42. caqti-lwt
  43. caqti-mirage
  44. carton < "1.0.0"
  45. carton-git
  46. carton-lwt
  47. catala-format >= "0.2.0"
  48. cf-lwt
  49. chamelon
  50. chamelon-unix
  51. chamo
  52. charrua-client
  53. charrua-unix
  54. chess_com_api
  55. ciao_lwt
  56. clz
  57. cmdtui-lambda-term
  58. coap
  59. coap-server-lwt
  60. cohttp-curl-lwt
  61. cohttp-lwt
  62. cohttp-lwt-jsoo
  63. cohttp-lwt-unix
  64. cohttp-mirage
  65. cohttp-server-lwt-unix
  66. comby
  67. comby-semantic
  68. conan-lwt
  69. conduit-lwt
  70. conduit-lwt-unix
  71. cowabloga
  72. crunch
  73. cstruct-lwt
  74. csv-lwt
  75. ctypes >= "0.15.0" & < "0.21.1"
  76. ctypes-foreign >= "0.21.1"
  77. curl_lwt
  78. current
  79. current-albatross-deployer
  80. current_docker
  81. current_examples
  82. current_git
  83. current_github
  84. current_gitlab
  85. current_ocluster
  86. current_rpc
  87. current_slack
  88. current_web
  89. dap
  90. data-encoding < "0.1.1"
  91. devkit >= "1.2"
  92. distributed-lwt
  93. dkim-bin < "0.8.0"
  94. dkim-lwt-unix
  95. dkim-mirage
  96. dlm
  97. dmarc
  98. dns-certify
  99. dns-cli
  100. dns-client < "7.0.3"
  101. dns-client-lwt
  102. dns-client-mirage
  103. dns-forward
  104. dns-forward-lwt-unix
  105. dns-lwt
  106. dns-mirage
  107. dns-resolver
  108. dns-server
  109. dns-stub
  110. dnsrobot
  111. dnssd
  112. docker_hub
  113. docteur >= "0.0.2"
  114. docteur-solo5
  115. docteur-unix >= "0.0.5"
  116. doi2bib
  117. dream
  118. dream-httpaf
  119. dream-pure
  120. dream-serve < "1.0.1"
  121. dropbox
  122. dune >= "3.17.2"
  123. dune-rpc-lwt
  124. earlybird
  125. elasticsearch-cli
  126. emoji = "2.0.0"
  127. equinoxe
  128. ethernet
  129. ez_api >= "1.2.0" & < "3.0.0"
  130. ezcurl-lwt
  131. ezjs_min < "0.2"
  132. ezjsonm-lwt
  133. ezresto
  134. ezresto-directory >= "0.5"
  135. faraday-lwt
  136. faraday-lwt-unix
  137. fat-filesystem
  138. fiber-lwt
  139. fsevents-lwt
  140. fswatch_lwt
  141. fuseau-lwt
  142. gdbprofiler
  143. git
  144. git-cohttp
  145. git-cohttp-unix
  146. git-kv >= "0.2.0"
  147. git-mirage
  148. git-paf
  149. git-unix >= "3.2.0"
  150. github
  151. github-hooks
  152. github-unix >= "4.4.0"
  153. gitlab-unix
  154. gitlab_pipeline_notifier
  155. gluten-lwt
  156. gluten-lwt-unix < "0.4.0"
  157. gluten-mirage < "0.4.0"
  158. graphql-lwt
  159. gremlin
  160. grpc-lwt
  161. guardian
  162. gufo
  163. h1
  164. h1-lwt-unix
  165. h2-lwt
  166. h2-lwt-unix < "0.10.0"
  167. h2-mirage
  168. happy-eyeballs-lwt
  169. happy-eyeballs-mirage
  170. hidapi-lwt
  171. hiredis >= "0.6"
  172. hl_yaml
  173. hockmd
  174. http-lwt-client
  175. http-mirage-client
  176. http-multipart-formdata >= "2.0.0" & < "3.0.0"
  177. httpaf-lwt-unix
  178. httpun-lwt
  179. httpun-mirage
  180. httpun-ws-lwt
  181. hvsock
  182. i3ipc
  183. influxdb-lwt
  184. inotify >= "2.4"
  185. inquire < "0.3.0"
  186. interface-prime-lwt
  187. ip2location
  188. ip2locationio
  189. ip2whois
  190. ipv6-multicast-lwt
  191. irc-client-lwt
  192. irc-client-lwt-ssl
  193. irc-client-tls
  194. irmin
  195. irmin-bench
  196. irmin-chunk
  197. irmin-cli
  198. irmin-client
  199. irmin-containers
  200. irmin-fs
  201. irmin-git
  202. irmin-graphql
  203. irmin-http
  204. irmin-indexeddb
  205. irmin-layers
  206. irmin-mirage-git
  207. irmin-mirage-graphql
  208. irmin-pack
  209. irmin-server
  210. irmin-test
  211. irmin-unix
  212. irmin-watcher
  213. joolog
  214. jose < "0.9.0"
  215. js_of_ocaml-lwt
  216. jsoo_broadcastchannel
  217. jsoo_storage
  218. jupyter
  219. jupyter-kernel
  220. kafka < "0.5"
  221. kafka_lwt
  222. kappa-library
  223. ke >= "0.5"
  224. kinetic-client
  225. kubecaml
  226. lambda-runtime
  227. lambda-term
  228. lambda_streams_lwt
  229. launchd
  230. ldp
  231. learn-ocaml
  232. learn-ocaml-client
  233. ledgerwallet >= "0.4.0"
  234. letsencrypt < "2.0.0"
  235. letsencrypt-app
  236. letsencrypt-dns < "2.0.0"
  237. letters
  238. lichess_api
  239. links
  240. llama
  241. lru_cache
  242. lwt-canceler
  243. lwt-dllist
  244. lwt-exit
  245. lwt-parallel
  246. lwt-pipe
  247. lwt-pipeline
  248. lwt-watcher
  249. lwt_camlp4
  250. lwt_direct >= "6.0.0~beta01"
  251. lwt_domain
  252. lwt_eio < "0.6"
  253. lwt_glib
  254. lwt_log
  255. lwt_ppx
  256. lwt_react
  257. lwt_retry
  258. lwt_ssl
  259. mariadb >= "1.2.0"
  260. markdown_monolith
  261. markup = "0.7.6"
  262. markup-lwt
  263. mdx
  264. mechaml
  265. mehari-lwt-unix
  266. mehari-mirage
  267. memtrace-mirage
  268. metrics-influx
  269. metrics-lwt
  270. metrics-unix
  271. migra
  272. mimic
  273. mindstorm-lwt
  274. mirage < "4.0.0"
  275. mirage-block >= "2.0.1"
  276. mirage-block-ccm
  277. mirage-block-combinators
  278. mirage-block-lwt
  279. mirage-block-partition
  280. mirage-block-ramdisk
  281. mirage-block-solo5
  282. mirage-block-unikraft
  283. mirage-block-unix >= "2.14.2"
  284. mirage-block-xen
  285. mirage-channel >= "4.0.1"
  286. mirage-channel-lwt
  287. mirage-clock-lwt
  288. mirage-clock-unix < "4.2.0"
  289. mirage-console-lwt
  290. mirage-crypto-rng < "0.11.3"
  291. mirage-crypto-rng-lwt
  292. mirage-crypto-rng-mirage
  293. mirage-device >= "2.0.0"
  294. mirage-flow >= "3.0.0"
  295. mirage-flow-combinators
  296. mirage-flow-lwt
  297. mirage-flow-unix
  298. mirage-fs >= "4.0.0"
  299. mirage-fs-lwt
  300. mirage-kv >= "3.0.1"
  301. mirage-kv-lwt
  302. mirage-kv-unix
  303. mirage-net >= "4.0.0"
  304. mirage-net-lwt
  305. mirage-net-macosx
  306. mirage-net-solo5
  307. mirage-net-unikraft
  308. mirage-net-unix
  309. mirage-net-xen
  310. mirage-profile
  311. mirage-protocols >= "7.0.0"
  312. mirage-protocols-lwt
  313. mirage-qubes
  314. mirage-qubes-ipv4
  315. mirage-runtime
  316. mirage-sleep
  317. mirage-solo5
  318. mirage-stack = "3.0.0"
  319. mirage-stack-lwt
  320. mirage-time >= "3.0.0"
  321. mirage-time-lwt
  322. mirage-time-unix
  323. mirage-types-lwt
  324. mirage-unikraft
  325. mirage-unix
  326. mirage-vnetif
  327. mirage-xen
  328. monorobot
  329. moonpool-lwt < "0.11"
  330. mqtt
  331. mrmime >= "0.5.0"
  332. multipart-form-data
  333. multipart_form >= "0.2.0" & < "0.4.0"
  334. multipart_form-cohttp-lwt < "0.6.0"
  335. multipart_form-lwt
  336. mwt
  337. naboris
  338. nbd >= "4.0.3"
  339. nbd-tool
  340. nbd-unix
  341. neo4j_bolt
  342. nocrypto
  343. nottui-lwt
  344. notty-community
  345. nproc
  346. nsq
  347. obuilder
  348. obus >= "1.2.1"
  349. ocaml-ai-sdk
  350. ocluster
  351. ocluster-api
  352. ocluster-worker
  353. ocplib-resto
  354. ocsigenserver
  355. ocsipersist
  356. ocsipersist-dbm
  357. ocsipersist-lib
  358. ocsipersist-pgsql
  359. ocsipersist-sqlite
  360. oframl
  361. ojs_base
  362. omigrate
  363. oneffs
  364. opam-check-npm-deps >= "4.1.0"
  365. opam-publish >= "3.0.0"
  366. opencage
  367. opentelemetry-client-cohttp-lwt
  368. opentelemetry-client-ocurl-lwt
  369. opentelemetry-cohttp-lwt >= "0.4"
  370. opentelemetry-lwt
  371. opium
  372. opium-graphql
  373. opium_kernel
  374. opomodoro
  375. order-i3-xfce
  376. ordma
  377. oskel >= "0.3.0"
  378. ounit-lwt < "2.2.0"
  379. ounit2-lwt
  380. owork
  381. ozulip
  382. paf
  383. paf-cohttp
  384. passage < "0.1.8"
  385. pcap-format < "0.5.2"
  386. petrol
  387. pgn_parser
  388. pgx_lwt
  389. pgx_lwt_mirage
  390. pgx_lwt_unix < "2.0"
  391. piaf < "0.2.0"
  392. picos >= "0.3.0" & < "0.5.0"
  393. picos_lwt
  394. picos_meta
  395. plebeia >= "2.0.0"
  396. plotkicadsch
  397. posix-getopt >= "4.0.2"
  398. ppx_defer >= "0.4.0"
  399. ppx_deriving_rpc
  400. ppx_rapper_lwt
  401. proc-smaps
  402. prof_spacetime
  403. prometheus
  404. prometheus-app
  405. promise_jsoo_lwt
  406. protocol-9p
  407. protocol-9p-unix
  408. proton
  409. pxshot
  410. qcow
  411. qcow-stream
  412. qcow-tool
  413. qcow-types
  414. qdrant < "0.2.0"
  415. qfs
  416. quests
  417. quickterface
  418. rawlink < "2.1"
  419. rawlink-lwt
  420. rdf_json_ld
  421. rdf_lwt
  422. redis-lwt
  423. reparse-lwt
  424. reparse-lwt-unix
  425. resource-pooling
  426. resp
  427. resp-mirage >= "0.10.0"
  428. resp-unix >= "0.10.0"
  429. resto
  430. resto-cohttp-client >= "0.4"
  431. resto-cohttp-self-serving-client
  432. resto-cohttp-server >= "0.4" & < "0.6" | >= "0.9"
  433. resto-directory >= "0.4"
  434. ringo-lwt
  435. river
  436. rock
  437. rpclib-js
  438. rpclib-lwt
  439. SZXX < "4.0.0"
  440. sanddb
  441. scgi
  442. sendmail-lwt
  443. sendmail-mirage
  444. serial
  445. server-reason-react
  446. session-cohttp-lwt
  447. session-cookie-lwt
  448. session-postgresql-lwt
  449. sessions
  450. shared-block-ring
  451. shared-memory-ring-lwt
  452. sherlodoc
  453. sihl < "0.2.0"
  454. slack
  455. slacko
  456. slipshow
  457. smtml >= "0.7.0"
  458. speed
  459. spin < "0.8.0"
  460. spoke
  461. statocaml
  462. stk
  463. stog
  464. swapfs
  465. syguslib-utils
  466. syndic >= "1.4" & < "1.6.0"
  467. tar-mirage
  468. tar-unix
  469. tcpip
  470. telegraml
  471. terminus
  472. testcontainers
  473. testo-lwt
  474. tezt
  475. tidy_email
  476. timmy-lwt
  477. tls >= "0.10.6" & < "0.16.0"
  478. tls-lwt
  479. tls-mirage
  480. tube
  481. tuntap
  482. twirp_cohttp_lwt_unix
  483. uring
  484. uspf
  485. uspf-lwt
  486. uspf-mirage
  487. utcp
  488. utop
  489. uwt
  490. vchan
  491. vchan-unix
  492. vchan-xen
  493. vercel
  494. vhd-format-lwt
  495. vmnet
  496. vue-jsoo < "0.3"
  497. wayland < "2.0"
  498. webauthn
  499. xen-evtchn
  500. xen-evtchn-unix
  501. xen-gnt
  502. xen-gnt-unix
  503. xenstore
  504. xenstore-tool
  505. xenstore_transport
  506. xlsx2csv
  507. yocaml_git
  508. yocaml_unix < "2.0.0"
  509. zarr-lwt
  510. zmq-lwt >= "5.2.1"

Conflicts

None