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 (34)

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.1.2.tar.gz
md5=00bc7eb2772a28530f7365a7040f0c4f
sha512=a4737a2fc44aaeedca46ec6134c07013d5cf44039a988a6e79a40715a53e43601d4c91bbf11a8e89540528d912b8fa487e3068465c136c1156a872258eb3443b

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: 29 Apr 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 resolved 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:

let () =
  let request =
    let%lwt 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) ->
      write outgoing "GET / HTTP/1.1\r\n";%lwt
      write outgoing "Connection: close\r\n\r\n";%lwt
      let%lwt response = read incoming in
      Lwt.return (Some response)))
  in

  let timeout =
    Lwt_unix.sleep 5.;%lwt
    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,lwt_ppx -linkpkg example.ml && ./a.out *)

If you are not using the lwt_ppx syntax extension, you can use the let* binding opoerators from the Lwt.Syntax module instead.

let () =
  let open Lwt.Syntax in
  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,lwt_ppx -linkpkg example.ml && ./a.out *)

In the program above, functions such as Lwt_io.write create promises. The let%lwt ... in construct (provided by lwt_ppx) or the let* ... in construct (provided by Lwt.Syntax) are used to wait for a promise to resolve. The code after in is scheduled to run after the code inside the let...in has resolved.

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. dune >= "3.18"

Dev Dependencies (2)

  1. odoc with-doc & >= "2.3"
  2. ocamlfind dev & >= "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. faraday-lwt
  135. faraday-lwt-unix
  136. fat-filesystem
  137. fiber-lwt
  138. fsevents-lwt
  139. fswatch_lwt
  140. gdbprofiler
  141. git
  142. git-cohttp
  143. git-cohttp-unix
  144. git-kv >= "0.2.0"
  145. git-mirage
  146. git-paf
  147. git-unix >= "3.2.0"
  148. github
  149. github-hooks
  150. github-unix >= "4.4.0"
  151. gitlab-unix
  152. gitlab_pipeline_notifier
  153. gluten-lwt
  154. gluten-lwt-unix < "0.4.0"
  155. gluten-mirage < "0.4.0"
  156. granary
  157. granary_repl
  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 >= "3.3.3"
  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"
  251. lwt_domain != "0.2.0"
  252. lwt_eio >= "0.6"
  253. lwt_ppx >= "6.0.0"
  254. lwt_react
  255. lwt_retry
  256. lwt_ssl
  257. mariadb >= "1.2.0"
  258. markdown_monolith
  259. markup = "0.7.6"
  260. markup-lwt
  261. mdx
  262. mechaml
  263. mehari-lwt-unix
  264. mehari-mirage
  265. memtrace-mirage
  266. metrics-influx
  267. metrics-lwt
  268. metrics-unix
  269. migra
  270. mimic
  271. mindstorm-lwt
  272. mirage < "4.0.0"
  273. mirage-block >= "2.0.1"
  274. mirage-block-ccm
  275. mirage-block-combinators
  276. mirage-block-lwt
  277. mirage-block-partition
  278. mirage-block-ramdisk
  279. mirage-block-solo5
  280. mirage-block-unikraft
  281. mirage-block-unix >= "2.14.2"
  282. mirage-block-xen
  283. mirage-channel >= "4.0.1"
  284. mirage-channel-lwt
  285. mirage-clock-lwt
  286. mirage-clock-unix < "4.2.0"
  287. mirage-console-lwt
  288. mirage-crypto-rng < "0.11.3"
  289. mirage-crypto-rng-lwt
  290. mirage-crypto-rng-mirage
  291. mirage-device >= "2.0.0"
  292. mirage-flow >= "3.0.0"
  293. mirage-flow-combinators
  294. mirage-flow-lwt
  295. mirage-flow-unix
  296. mirage-fs >= "4.0.0"
  297. mirage-fs-lwt
  298. mirage-kv >= "3.0.1"
  299. mirage-kv-lwt
  300. mirage-kv-unix
  301. mirage-net >= "4.0.0"
  302. mirage-net-lwt
  303. mirage-net-macosx
  304. mirage-net-solo5
  305. mirage-net-unikraft
  306. mirage-net-unix
  307. mirage-net-xen
  308. mirage-profile
  309. mirage-protocols >= "7.0.0"
  310. mirage-protocols-lwt
  311. mirage-qubes
  312. mirage-qubes-ipv4
  313. mirage-runtime
  314. mirage-sleep
  315. mirage-solo5
  316. mirage-stack = "3.0.0"
  317. mirage-stack-lwt
  318. mirage-time >= "3.0.0"
  319. mirage-time-lwt
  320. mirage-time-unix
  321. mirage-types-lwt
  322. mirage-unikraft
  323. mirage-unix
  324. mirage-vnetif
  325. mirage-xen
  326. monorobot
  327. mqtt
  328. mrmime >= "0.5.0"
  329. multipart-form-data
  330. multipart_form >= "0.2.0" & < "0.4.0"
  331. multipart_form-cohttp-lwt < "0.6.0"
  332. multipart_form-lwt
  333. naboris
  334. nbd >= "4.0.3"
  335. nbd-tool
  336. nbd-unix
  337. neo4j_bolt
  338. nottui-lwt
  339. notty-community
  340. nproc
  341. nsq
  342. obuilder
  343. obus >= "1.2.1"
  344. ocaml-ai-sdk
  345. ocluster
  346. ocluster-api
  347. ocluster-worker
  348. ocplib-resto
  349. ocsigenserver
  350. ocsipersist
  351. ocsipersist-dbm
  352. ocsipersist-lib
  353. ocsipersist-pgsql
  354. ocsipersist-sqlite
  355. oframl
  356. ojs_base
  357. omigrate
  358. oneffs
  359. opam-check-npm-deps >= "4.1.0"
  360. opam-publish >= "3.0.0"
  361. opencage
  362. opentelemetry-client-cohttp-lwt
  363. opentelemetry-client-ocurl-lwt
  364. opentelemetry-cohttp-lwt >= "0.4"
  365. opentelemetry-lwt
  366. opium
  367. opium-graphql
  368. opium_kernel
  369. opomodoro
  370. order-i3-xfce
  371. ordma
  372. oskel >= "0.3.0"
  373. ounit-lwt < "2.2.0"
  374. ounit2-lwt
  375. owork
  376. ozulip
  377. paf
  378. paf-cohttp
  379. passage < "0.1.8"
  380. pcap-format < "0.5.2"
  381. petrol
  382. pgn_parser
  383. pgx_lwt
  384. pgx_lwt_mirage
  385. pgx_lwt_unix < "2.0"
  386. piaf < "0.2.0"
  387. picos >= "0.3.0" & < "0.5.0"
  388. picos_meta
  389. plebeia >= "2.0.0"
  390. plotkicadsch
  391. posix-getopt >= "4.0.2"
  392. ppx_defer >= "0.4.0"
  393. ppx_deriving_rpc
  394. ppx_rapper_lwt
  395. proc-smaps
  396. prof_spacetime
  397. prometheus
  398. prometheus-app
  399. promise_jsoo_lwt
  400. protocol-9p
  401. protocol-9p-unix
  402. proton
  403. pxshot
  404. qcow
  405. qcow-stream
  406. qcow-tool
  407. qcow-types
  408. qdrant < "0.2.0"
  409. qfs
  410. quests
  411. quickterface
  412. rawlink < "2.1"
  413. rawlink-lwt
  414. rdf_json_ld
  415. rdf_lwt
  416. redis-lwt
  417. reparse-lwt
  418. reparse-lwt-unix
  419. resource-pooling
  420. resp
  421. resp-mirage >= "0.10.0"
  422. resp-unix >= "0.10.0"
  423. resto
  424. resto-cohttp-client = "0.4"
  425. resto-cohttp-server = "0.4"
  426. resto-directory = "0.4"
  427. ringo-lwt
  428. river
  429. rock
  430. rpclib-js
  431. rpclib-lwt
  432. SZXX < "4.0.0"
  433. sanddb
  434. scgi
  435. sendmail-lwt
  436. sendmail-mirage
  437. serial
  438. server-reason-react
  439. session-cohttp-lwt
  440. session-cookie-lwt
  441. session-postgresql-lwt
  442. sessions
  443. shared-block-ring
  444. shared-memory-ring-lwt
  445. sherlodoc
  446. sihl < "0.2.0"
  447. slack
  448. slacko
  449. slipshow
  450. smtml >= "0.7.0"
  451. speed
  452. spin < "0.8.0"
  453. spoke
  454. statocaml
  455. stk
  456. stog
  457. swapfs
  458. syguslib-utils
  459. syndic >= "1.4" & < "1.6.0"
  460. tar-mirage
  461. tar-unix
  462. tcpip
  463. telegraml
  464. terminus
  465. testcontainers
  466. testo-lwt
  467. tidy_email
  468. tls >= "0.10.6" & < "0.16.0"
  469. tls-lwt
  470. tls-mirage
  471. tube
  472. tuntap
  473. twirp_cohttp_lwt_unix
  474. uring
  475. uspf
  476. uspf-lwt
  477. uspf-mirage
  478. utcp
  479. utop
  480. uwt
  481. vchan
  482. vchan-unix
  483. vchan-xen
  484. vercel
  485. vhd-format-lwt
  486. vmnet
  487. vue-jsoo < "0.3"
  488. wayland < "2.0"
  489. webauthn
  490. xen-evtchn
  491. xen-evtchn-unix
  492. xen-gnt
  493. xen-gnt-unix
  494. xenstore
  495. xenstore-tool
  496. xenstore_transport
  497. xlsx2csv
  498. yocaml_git
  499. yocaml_unix < "2.0.0"
  500. zarr-lwt
  501. zmq-lwt >= "5.2.1"

Conflicts

None